About webhooks

A webhook is a request another service sends your app when something happens, such as a payment going through. Webhooks sit between those senders and your app: they receive every webhook, keep it, and deliver it to your app, trying again until your app takes it.

Everything belongs to a project, and you set it up with a few pieces.

Sources, destinations, and connections

• A source is an address senders send webhooks to, such as https://hooks.digitospace.com/in/src_k7m2q9x4v1c8r3t6w0z5b2n8h4j6p1d3. Give it to the service that sends the webhooks. See Receive webhooks.
• A destination is where webhooks go: an HTTPS address in your app, with the authentication, rate limit, and retries to use. See Deliver webhooks.
• A connection joins a source to a destination. It can hold a filter that picks which webhooks to send, a delay, and a transformation that changes each webhook before it is sent.

A source can have many connections, so one webhook can go to several destinations. A destination can take webhooks from several sources.

Events, deliveries, and attempts

• An event is one webhook we received: its method, path, query, headers, and body.
• A delivery is one event on its way to one destination. An event that three connections take makes three deliveries.
• An attempt is one try at sending a delivery.

A delivery is delivered when your app answers an attempt with a 2xx status. Otherwise it is tried again after a wait, and after the destination’s last attempt it is failed. You can send any delivery again, and cancel one that is still waiting. See Retries and rate limits.

Nothing sent to us is lost

Once a sender gets a 200 from a source, the webhook is kept, even while your app is down, and delivered when your app is back. An event that no connection takes is kept too, as filtered, so you can see what arrived.

Events and their deliveries are kept for 30 days.

At least once

Each delivery reaches your app at least once. In rare cases, such as a network failure after your app has handled an attempt but before we see its answer, the same delivery reaches your app more than once.

Every attempt carries a webhook-id header, the event’s ID, which stays the same on every attempt and when a delivery is sent again. Record the IDs your app has handled, and when one comes again, answer with a 2xx status and do nothing. See Request headers.

Signed deliveries

Every attempt is signed with the destination’s signing secret, so your app can check that it came from us, unchanged. See Verify deliveries to your app.

Addresses we deliver to

We deliver to HTTPS addresses on the public internet. Addresses on private networks, and names that resolve to them, are never called, and the attempt fails with the class blocked. Redirects are not followed.

Ways to manage webhooks

Set up sources, destinations, and connections through the REST API or the JavaScript SDK. In the console, open Webhooks in a project to do the same, see every event and delivery, send failed deliveries again, and try a transformation.