Webhooks

Configure a new endpoint

Stable can send webhooks to your endpoint when something notable changes, such as when you receive new mail at an address. You manage your endpoints in the Stable dashboard.

1. In the dashboard, go to Developer > Webhooks.
2. Add the URL of your endpoint.
3. Select the events you want to receive. You do not need to listen for all events.
4. Copy the endpoint secret used to sign webhook events. You can view this again at a later time.

Check signatures

When we deliver events to your endpoint, we'll sign the request with an HMAC with SHA-256. The signing secret is unique to your account and the specific webhook endpoint.

Stable's webhooks use Svix's format. We recommend you use the Svix libraries to easily verify your signature.

In general:

1. Read the raw request body.
2. Pass the body, headers, and the endpoint secret to the Svix library, or to a custom implementation.
3. If the signature check fails, return a 400 and stop handling the request.

If you prefer to implement signature verification manually, you can also follow this guide.

Testing webhooks

You can test webhooks using example payloads directly in the Stable dashboard.

• In the dashboard, go to Developer > Webhooks.

• Select the affected endpoint.

• Select the "Testing" tab, then select and trigger an event.

Best practices

1. Make your endpoint resilient to retries by refetching presigned URLs that may have expired prior to redelivery. The typical expiration period is 24 hours, but refer to the event documentation for specifics.
2. Do not assume that events are delivered with guaranteed ordering. For example, a mail item lifecycle event may be processed out of order if your system processes webhooks in parallel.

Retries

If your endpoint does not return a success response, we try to redeliver the event. We first retry immediately, then after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours. After 5 days of failures, we disable the endpoint. It's important to monitor the error rates of your webhook handler to prevent a disruption in event delivery.

Replay events

If you need to replay events for any reason, you can replay up to 90 days of events from the Stable dashboard. You can replay a single message, all messages, failed messages, or messages with a specific response code.

1. In the dashboard, go to Developer > Webhooks.
2. Select the affected endpoint.
3. Select "Replay" from the menu, then select an option.

As noted above, ensure you are prepared to handle expired presigned URLs in your handler before initiating a replay.

Events

For the full list of events and their payloads, see the Stable Webhooks section in the sidebar.