Webhooks 101

Learn what webhooks are, how they work, some common use cases and best practices.

What are webhooks?

Webhooks are a way for an application to send real-time data or event notifications to another application when specific events occur. They act as event-driven HTTP callbacks triggered by predefined events, automatically pushing data to a URL endpoint specified by the receiving system.

For example, you can set up GitHub to notify you when a new pull request is created by sending a webhook to the Slack channel where your development team communicates. This allows the team to be instantly informed without needing to manually check GitHub.

What are webhooks used for?

Webhooks are commonly used in a variety of scenarios, including:

• Payment Systems: Notifying when a payment is successful or fails. For example, Stripe uses webhooks to notify merchants of successful payments or failed charges.
• Continuous Integration (CI): Triggering automated builds or tests when new code is pushed to a repository. For example, GitHub uses webhooks to notify CI services like Travis CI or CircleCI of new commits.
• E-commerce: Updating inventory levels or notifying when an order is placed or shipped. For example, Shopify uses webhooks to notify merchants of new orders.
• Messaging Systems: Chat notifications when a new message is received. For example, chatbots are typically implemented using webhooks to receive messages from users and respond accordingly.
• CRM: Triggering workflows when customer data changes. For example, Salesforce uses webhooks to notify external systems of changes to customer records.

In short, webhooks are great any time you want to notify (or be notified) of a server-side event without needing to poll for changes.

How do webhooks work?

Webhooks typically work by having a third-party service (eg. GitHub) send an HTTP POST request to a URL you specify (your server or another third-party service).

Here's a high-level overview of how to handle a webhook:

1. Event Trigger: An event (e.g., a payment processed, a file uploaded) happens in the source application.
2. HTTP Request: The source application sends an HTTP request (usually POST) to a predefined URL on the receiving application. This request contains data related to the event.
3. Processing: The receiving application processes the incoming data, usually by executing some form of logic (e.g., updating a database, triggering a workflow).
4. Response: The receiving server returns an HTTP status code (often 200 for success) to acknowledge receipt. If the request fails (e.g., the server is down), the source application may retry sending the webhook.

Webhooks vs REST APIs

Let's get this out of the way: webhooks are just HTTP requests. What makes them different is how they're used.

You could think of them as user-defined HTTP callbacks. Instead of a request initiated by a client (like a browser or mobile app), webhooks are initiated by a server and sent to a URL you specify.

With that said, here's how they differ from REST APIs:

• REST APIs: Behave like your typical client-server application. The client sends a request to the server, and the server responds with the data. The client controls when the request is made (pull).
• Webhooks: The server pushes data to the client automatically as soon as the event occurs, reducing the need for polling to check if something has changed (push).

Webhooks are preferred for when your application needs to react to events, while REST APIs are useful when the client needs control over the timing and volume of requests

Webhook best practices

When working with webhooks, it's important to consider the following:

• Security: Ensure the webhook URL is protected and served over HTTPS. Also verify the authenticity of incoming requests for sensitive applications (e.g. Stripe and Paddle include a signature in the request headers).
• Retries: Handle retries properly, as the source system may attempt to resend failed webhook requests. Implement idempotency to avoid processing the same event multiple times.
• Timeouts: Set reasonable timeouts for processing webhooks. If the receiving system is slow, the source might drop the webhook or consider it failed.
• Rate Limits: Be aware of the frequency of webhook requests, especially during high-traffic events. Implement rate limiting to prevent overloading the system.
• Versioning: Consider versioning your webhooks to ensure backward compatibility as you make changes to the payload structure.
• Testing: Use tools to simulate webhooks to ensure the receiving system behaves as expected under various conditions.

Next: Testing Webhooks