Reference · Trust and verification
Webhook payload
The event shape, the signature header, and replay.
The webhook event shape, the signature header, and replay.
Verify first, process after#
Your webhook endpoint accepts POSTs from anyone who finds its URL. Verify the signature before reading the payload.
Headers#
| Header | Carries |
|---|---|
hideguard-signature | The signature over the body |
hideguard-delivery | A unique id for this delivery |
hideguard-event | The event type |
Replay#
hideguard-delivery is unique per delivery. Store the ids you have processed and skip duplicates.
A failed delivery is retried, so your endpoint has to be idempotent whether or not an attacker is involved.
Return quickly#
Answer 2xx as soon as you have stored the event, then process it. An endpoint that works synchronously for several seconds is counted as a timeout and gets retries it does not need.
The guard on our side#
Every request to a URL you supply goes through an address check inside the socket's own DNS lookup: not a check first and a connection after. A hostname can answer differently between two lookups, and 169.254.169.254 is the cloud providers' metadata endpoint.
Registering and inspecting deliveries#
Webhooks on the dashboard.