Glossary · 4 · Platform SDKs and extensions
Webhook
Also known as: Web hook, HTTP callback, Outgoing webhook
In web integration, a webhook is an HTTP request, usually a POST with a JSON payload, that a platform sends to a URL registered by a subscriber when a specified event occurs, so that the subscriber is notified immediately instead of polling the platform for changes.
- Platform SDKs
- Developer SDKs
In one sentence
A webhook is an HTTP request a platform sends to a subscriber's URL when an event occurs, replacing polling; it should be signed and verified.
Example
When a pull request is merged, the code hosting platform sends a webhook to the documentation build service, which starts a new build of the SDK reference.
How it applies
- Platform SDKs: Webhooks let external systems react to what happens on a platform (a record changed, a payment completed, a build finished) without being installed inside it. They complement in-platform extensions and are a building block of an event-driven architecture across organizations.
- Developer SDKs: SDKs often include helpers to verify webhook signatures and to parse payloads into typed objects. OpenAPI 3.1 and later can describe incoming webhooks alongside regular operations.
- Authenticity: The receiver must check that a request really comes from the platform. The usual method is a signature computed with a shared secret, for example an HMAC-SHA256 hash sent in a header (GitHub uses
X-Hub-Signature-256); some providers use asymmetric signatures. Timestamps and unique message IDs let receivers reject replayed messages. - Delivery and retries: Webhooks can fail when the receiver is down or slow. Providers differ: some retry with backoff, while GitHub, for example, does not redeliver failed deliveries automatically. Receivers should answer quickly, process asynchronously and handle duplicates; processing must therefore be idempotent.
- Documentation: Webhook documentation lists the events, payload schemas, signature method, retry policy, ordering guarantees (often none) and how to test deliveries.
- Standardization: There is no IETF or W3C standard for webhooks. The community specification Standard Webhooks defines common headers (
webhook-id,webhook-timestamp,webhook-signature) and signature schemes; adoption varies by provider.
Webhook vs. polling
With polling the client asks repeatedly whether something changed, which costs requests and adds delay. With a webhook the platform pushes the notification when the event happens. Polling remains useful as a fallback, for reconciliation after missed deliveries and where the client cannot expose a public URL.