Consuming Events

Verifying Webhook Events

When your application receives a webhook event, it should verify the request's authenticity before processing the event. This protects your application against forged webhook requests and replay attacks.

Webhook verification involves two checks:

1. Signature Verification: Each webhook request includes a cryptographic signature that allows your application to verify that the event originated from Svix and that its contents have not been modified. Without signature verification, malicious actors could send forged events to your webhook endpoint.
2. Timestamp Verification: Each webhook request includes a timestamp indicating when it was sent. Your application should reject requests with timestamps outside an acceptable time window to prevent replay attacks, where an attacker resends a previously valid webhook request.

Svix provides webhook verification libraries for several programming languages that handle both signature and timestamp verification automatically.

For implementation details, refer to the following Svix documentation:

• How to Verify Webhooks — Use a Svix library to verify incoming webhook requests.

• Manual Webhook Verification — Implement verification manually if a library is not available for your programming language.

Acknowledging Webhook Events

Your webhook endpoint must acknowledge successful receipt of an event by returning an HTTP 2xx status code (200–299) within 15 seconds.

Svix considers any non-2xx response or request that exceeds the configured timeout a failed delivery. Failed deliveries are automatically retried according to Svix's retry policy.

For webhook handlers that perform time-consuming operations, we recommend validating the request, placing the event in a queue for asynchronous processing, and returning a successful response immediately after the event has been durably queued.

This prevents lengthy processing operations from causing webhook delivery timeouts.

Handling Failed Webhook Deliveries

Svix automatically retries failed webhook deliveries and provides tools for manually replaying events when necessary.

Automatic Retries

When a webhook delivery fails, Svix automatically attempts to redeliver the event according to a predefined retry schedule.

The retry delays are as follows:

If all delivery attempts fail, Svix marks the message as Failed for that endpoint.

Manual Retries

You can manually retry failed webhook deliveries through the Svix Consumer App Portal. This is useful when recovering from temporary outages, endpoint configuration issues, or other delivery failures.

To replay multiple webhook events:

1. In the Svix Consumer App Portal, select Endpoints from the left navigation menu.
2. Select the endpoint whose messages you want to replay.
3. Click Replay and select the set of messages you want to redeliver.

To replay an individual event, locate the message in the endpoint's delivery history and click the replay button next to the corresponding delivery attempt.

Disabled Endpoints

If webhook deliveries to an endpoint continue to fail for five days, Svix automatically disables the endpoint to prevent further unsuccessful delivery attempts.

To re-enable a disabled endpoint:

1. In the Svix Consumer App Portal, navigate to Endpoints.
2. Locate the disabled endpoint in the endpoints list.
3. Open the endpoint's options menu and select Enable Endpoint.

After re-enabling the endpoint, you may need to manually replay webhook events that failed or were missed during the outage. See the Manual Retries section for instructions.

Receiving Webhook Events Locally

During development, you can use the Svix CLI to forward webhook events to an endpoint running on your local machine.

The Svix CLI provides a listen command that generates a publicly accessible URL and forwards incoming webhook requests to your local endpoint.

For example, to receive events at http://localhost:8080/webhooks/wristband, run:

svix listen http://localhost:8080/webhooks/wristband

The command produces output similar to the following:

Webhook relay is now listening at
https://play.svix.com/in/c_pSbznmV2KCg38CY7zYpFBUktsgl/

All requests on this endpoint will be forwarded to your local url:
http://localhost:8080/webhooks/wristband

View logs and debug information at
https://play.svix.com/view/c_pSbznmV2KCg38CY7zYpFBUktsgl/

To disable logging run "svix listen --no-logging"

Next, create a webhook endpoint in the Svix Consumer App Portal using the generated play.svix.com URL.

For the example above, the endpoint URL would be:

https://play.svix.com/in/c_pSbznmV2KCg38CY7zYpFBUktsgl/

Once configured, webhook events delivered to this endpoint are automatically forwarded to your local application at http://localhost:8080/webhooks/wristband.

You can also use the Svix Play URL provided in the CLI output to inspect incoming requests and troubleshoot webhook delivery issues.

Troubleshooting

If your webhook endpoint is failing to receive or process events, consider the following common issues:

1. Incorrect Payload Used for Signature Verification: Svix signs the original request body. Parsing the JSON payload and serializing it again can change its representation, causing signature verification to fail. Always use the raw request body when verifying webhook signatures.
2. Incorrect Signing Secret: Each webhook endpoint has its own unique signing secret. Make sure your application uses the signing secret associated with the endpoint receiving the event.
3. Incorrect HTTP Response Status: Svix considers any 2xx response a successful delivery, regardless of the response body. If your application cannot accept or durably queue an event, return an appropriate non-2xx status code so Svix can retry the delivery.
4. Request Timeouts: If your endpoint takes longer than the configured timeout to respond, Svix considers the delivery unsuccessful. Avoid performing long-running operations directly in your webhook handler. Instead, queue the event for asynchronous processing and return a 2xx response once it has been durably accepted.