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.

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

Build your webhook handler

Best practices

Return HTTP 200 when you're confident the event has been captured by your system. Although we can replay these events, this ensures you don't miss anything silently.
Make your endpoint idempotent to prevent duplicate processing on retried or replayed events.
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.
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.

Check event 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:

Read the raw request body.
Pass the body, headers, and the endpoint secret to the Svix library, or to a custom implementation.
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.

Test your 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.

Retry behavior

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.

In the dashboard, go to Developer > Webhooks.
Select the affected endpoint.
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. Or, get started with these: