Integration Security
Webhook receivers need verification before automation
A webhook endpoint should prove the delivery is authentic before it starts business work. Verification, replay tracking and an event ledger make the automation easier to trust and support.
Treat delivery as intake, not permission to act
A webhook is only a delivery mechanism. It is not proof that the event is genuine, fresh, complete or safe to apply. A practical receiver separates intake from business processing: capture the raw request, verify the sender, check whether the delivery has already been seen, then enqueue or record the intended business action.
That separation matters when a sales update, payment event, repository change or support notification can trigger downstream work. If the endpoint jumps directly from HTTP request to system update, the team has little evidence when a delivery is disputed or retried.
Verify the raw payload before parsing decisions
GitHub documents the use of a webhook secret and an X-Hub-Signature-256 header, where the receiver calculates an HMAC SHA-256 value over the payload and compares it with the supplied signature. The docs also warn against plain equality comparison and note that proxies or load balancers must not modify payloads before verification.
The operating takeaway is straightforward: verify the exact raw body first. Parse JSON only after the signature passes. Store the verification result, delivery identifier where the provider supplies one, received timestamp and handler version. A failed signature should not become a generic integration error; it should be a security-relevant intake rejection.
Add a replay window and idempotency key
Signature validation proves integrity against the shared secret, but it does not by itself answer whether the same delivery was replayed or already processed. Keep a deduplication table keyed by provider delivery ID or a stable hash of the provider event identity. Include a time window appropriate to the provider and business process.
For actions that change state, use an idempotency boundary around the business effect. If the same event arrives twice, the second delivery should find the existing event record and avoid creating a second task, invoice, notification or status transition.
Make failures reviewable
Webhook failures should have meaningful states: signature missing, signature mismatch, malformed payload, unsupported event type, stale replay, duplicate delivery, handler failed, downstream system unavailable. Each state needs a safe retry or closure path.
Do not ask support to inspect raw logs for every failed event. A small event ledger with payload metadata, verification status, handler outcome and next action often gives operators enough to decide whether to replay, ignore, escalate or fix configuration.
Start with one provider and one event family
The smallest useful build is one provider, one event family and one downstream action. Once the team can see verified intake, duplicate behavior, failure states and support ownership, the same pattern can extend to more providers. Quarro can help implement the receiver, event ledger and workflow handoff without turning a webhook into an invisible production trigger.