Webhooks
Most important commands to remember
curl --data …— send an HTTP POST payload.curl -i— inspect the receiver’s status and response headers.
Commands and flags
| Option or argument | Meaning |
|---|---|
--data '{…}' |
Send the quoted JSON body and use POST. |
-H 'Content-Type: application/json' |
Declare JSON format. |
-H 'X-Lab-Event-ID: lab-1' |
Supply a custom test identifier, not a provider-standard signature. |
-i --max-time 5 |
Show headers and bound the transfer to five seconds. |
Both commands intentionally reuse the same event ID. Quotes preserve the JSON and header strings.
The concepts that matter
1. A webhook is an HTTP callback
A webhook sends an event from a provider to a receiver’s configured HTTP endpoint. Instead of polling repeatedly for changes, the receiver accepts incoming notifications.
The callback endpoint is an API that must validate requests, enforce size limits, and respond according to the provider’s contract. A JSON document arriving there is not automatically a trusted event, even when its fields resemble a real provider payload.
2. Authenticity must be checked before acting
Providers commonly sign payloads or supply another authentication mechanism. Signature validation must follow that provider’s exact scheme, often including the original raw body and a timestamp. Reformatting JSON before verification can change the signed bytes.
HTTPS protects the connection, while signature validation helps establish event origin and integrity. Neither a familiar source header nor an event ID is proof of authenticity. Replay protection and secret rotation also belong to the receiver’s design.
3. Deliveries can repeat or arrive out of order
A sender may retry after a timeout or failure, including when the receiver completed work but its acknowledgment was lost. Event order may differ from the order in which business changes occurred.
Use stable event identifiers and durable duplicate handling where the provider supplies them. The side effect and processed-event record should be coordinated so a crash cannot leave a misleading deduplication result. Merely remembering IDs in process memory is lost on restart.
4. Acknowledgment defines a responsibility boundary
A successful HTTP response can mean the receiver accepted responsibility, not that every downstream action finished. A common design validates, durably queues the event, and then acknowledges; workers handle longer processing afterward.
Acknowledging before durable acceptance risks losing the event after a crash. Waiting for slow downstream work can trigger unnecessary redelivery. The receiver’s response contract and internal durability need to agree.
One small example
Optional: use only the disposable local receiver described above. These are test deliveries, not signed events from a real provider.
curl -i --max-time 5 -H 'Content-Type: application/json' -H 'X-Lab-Event-ID: lab-1' --data '{"type":"lab.ping"}' http://127.0.0.1:8080/webhook
curl -i --max-time 5 -H 'Content-Type: application/json' -H 'X-Lab-Event-ID: lab-1' --data '{"type":"lab.ping"}' http://127.0.0.1:8080/webhookCompare the two responses and the receiver’s local logs. The ID remains lab-1, so a receiver implementing this lab’s deduplication should avoid performing its effect twice. Identical 2xx responses alone cannot prove that: inspect the effect or processing record.
A signature-enforcing production receiver should not accept this unsigned test as authentic. Connection refusal means the lab endpoint is absent. A 4xx may mean the receiver does not accept this payload or custom identifier.
No sender retry mechanism is exercised; you manually repeat delivery. The receiver may retain its test event record, which should be cleared through that lab’s normal reset procedure if you want a fresh run.
Keep this idea: Authenticate the event, make repeated delivery safe, and acknowledge only at a clearly defined durable boundary.