webhook delivery
POST {receiver_url} -> 2xx acknowledgement
An outbound HTTP request a service makes to a customer-supplied URL when an event occurs, replacing the need for the customer to poll for changes.
larsggu.me
A working reference for the vocabulary of business software integration over HTTP: how requests and events move, how an application proves who it acts for, what shape a response holds to across versions, and what keeps the arrangement correct once it is running. Every definition and every example below is written against the published HTTP, OAuth 2.0, SAML and SCIM specifications rather than any one vendor’s service, so the terms mean the same thing whichever product they turn up in.
Transport
4 entriesHow requests and events move between the two sides.
Identity
4 entriesHow an application proves who it is and who it acts for.
Data shape
3 entriesThe shapes a response is expected to hold to over time.
Operations
3 entriesWhat keeps an integration correct once it is running.
Selected entries
idempotency key
Idempotency-Key: <client-generated unique string>
A caller-supplied identifier that lets a request be repeated safely, because the server records the outcome against the key and replays it instead of acting twice.
rate limit headers
RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset / Retry-After
The response headers by which a service tells a caller how much of its quota is left and when it resets, so the caller can pace itself rather than discover the limit by being refused.
cursor pagination
GET /collection?limit=n[&after=<cursor>] -> {data, next_cursor}
Paging through a collection with an opaque position marker rather than a numeric offset, so that concurrent writes do not cause rows to be skipped or repeated.
error envelope
{"error":{"type","message","detail","request_id"}}
A single response shape for every failure, so that a caller can write one handler rather than one per endpoint.
tenant isolation
every query, key and cache entry carries tenant_id
The guarantee that one customer's data in a shared system cannot be read, written or inferred by another, enforced at the query layer rather than in application logic.
Two exchanges in full
A signed delivery and its acknowledgement
POST /hooks/inbound HTTP/1.1
Host: receiver.example
Content-Type: application/json
Event-Id: ev_8fd21c
Delivery-Id: dl_41ab90
Event-Type: invoice.settled
Timestamp: 2026-09-06T09:14:22Z
Signature: sha256=4c1b...9ae0
{"event":"invoice.settled","object":"invoice","id":"in_3390","state":"settled"}
HTTP/1.1 202 Accepted
Content-Length: 0Only the acknowledgement ends the delivery cycle; anything else is retried.
Delivery, retry and parking. Only a 2xx ends the cycle.
A cursor round trip
GET /v1/invoices?limit=2 HTTP/1.1
HTTP/1.1 200 OK
{"data":[{"id":"in_3390"},{"id":"in_3391"}],
"next_cursor":"Y3Vyc29yOjMzOTE"}
GET /v1/invoices?limit=2&after=Y3Vyc29yOjMzOTE HTTP/1.1
HTTP/1.1 200 OK
{"data":[{"id":"in_3392"}],
"next_cursor":null}The read ends on a null cursor, never on a short page.
Document status
The reference currently carries twelve definition entries across four topics, one guide chapter covering the stages of an integration, and one worked example. Entries are written once and revised in place rather than superseded, so a link to an entry keeps its meaning.
Last modified 2026-09-06. Full changelog.