Card 06/ 10
Webhooks: Another Server Calls Yours
A payment provider sends an HTTP POST to your endpoint when something happens on its side.
A webhook is an HTTP request that another company's server sends to a URL you registered, when something happens on its side: a payment succeeded, a commit was pushed. It is server to server, with no browser involved, and it means you do not have to keep asking the other service whether anything has changed.
Who starts, and which way. The sender starts every exchange. Your server only answers, and the sender decides when, and how often, it calls.
Trust nothing until it is signed. Your endpoint is a public URL, so anyone can post to it. The sender signs each request with a secret only you and it know, using a hash-based message authentication code (HMAC). Stripe sends its signature in a Stripe-Signature header, with a timestamp so an old request cannot be replayed; GitHub sends X-Hub-Signature-256. Check it before acting on anything.
Answer fast, work later. The sender waits for your reply, and treats a slow one as a failure. GitHub expects a 2xx response within 10 seconds. So store the event, reply, and do the work afterwards.
What it costs your server. Nothing between events: no open connection, no polling. The cost lands on the receiving side: an endpoint that must stay up, check signatures, and cope with the same event arriving twice.
Use it when
- Another service has the news, and your server must react, such as a payment confirmation
- Events are occasional, so polling for them would mostly come back empty
Avoid it when
- The receiver is a browser or phone, which has no public address to call
- You cannot run an endpoint that stays reachable
One product that uses it. Stripe tells a shop that a payment succeeded by posting a payment_intent.succeeded event to the shop's webhook endpoint.
So treat a webhook as an untrusted request on the sender's schedule: verify it, record it, answer at once, and do the work afterwards.
← → move through sections and cards