Deliver webhooks

A destination is where webhooks go: an HTTPS address in your app, with how to send to it. Once a connection joins it to a source, every webhook the source takes is delivered to it.

Create a destination

curl -X POST "$HOOKS_URL/destinations" \
  -H "Authorization: Bearer $HOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Orders service",
    "url": "https://orders.example.com/webhooks/payments",
    "auth": { "kind": "bearer", "token": "sk_live_4f9a2c7e1b" },
    "rateLimit": { "count": 10, "period": "second" },
    "maxAttempts": 8,
    "timeoutSeconds": 20
  }'

Only name and url are required. See Destinations for every field.

What each delivery sends

• The method the webhook was received with, unless the destination sets method to POST, PUT, or PATCH.
• The body exactly as it was received, or as a transformation changed it.
• The sender’s headers, apart from those that only mean something on the way, such as Host and Content-Length.
• The destination’s authentication, which replaces any header of the same name.
• Signing and tracing headers, so your app can check the delivery and tell attempts apart. See Request headers.

Each attempt waits at most timeoutSeconds for your app to answer, 30 seconds by default. Answer with a 2xx status as soon as the webhook is saved, and do slow work afterwards.

Authentication

Choose how we prove to your app that the delivery is ours, as well as the signature every delivery carries:

The credentials are kept secret. Reading a destination shows only auth.kind, and auth.header for the header kind. To keep the credentials when you change other fields, send auth again with them, or leave auth out.

Keep the address secret

When the address itself holds a secret, such as a token in its query, set urlSecret to true. Reading the destination then shows url as null. To change other fields and keep the address, leave url empty and urlSecret true.

Pause a destination

Set state to paused while your app is down for maintenance or you need to stop deliveries. Nothing is lost: deliveries for a paused destination wait, and are sent once you set state back to enabled.

Failing destinations

After 3 failed attempts in a row, a destination shows as failing, with failing set to true and failingSince saying when it started. One successful attempt clears it.

When a delivery fails for good, the people who can manage the project’s webhooks get an email, at most one a day for each destination, with a link to its failed deliveries.

Delete a destination

Deleting a destination deletes its connections and its deliveries, and cannot be undone. Events stay with their sources.