SHshieldlabs
Webhooks

Endpoint verification

Sent when you verify an endpoint in the analytics dashboard. It carries no data. A 2xx answer within 5 seconds marks the endpoint as verified; anything else marks the verification as failed.

The body is signed exactly like identification.scored. Its keys are sorted alphabetically and created_at has second precision. Worked example with the test secret whsec_00112233445566778899aabbccddeeff: the body

{"created_at":"2026-09-30T12:34:56Z","event_type":"webhook.ping","schema_version":"2026-06-01"}

arrives with X-Shield-Signature: sha256=ea2685733d254f7028fb031c4214583b0650de01e6c8c93131236024edd9fdd8.

postWebhookwebhook.ping

Headers

X-Shield-Signaturestring required

sha256= followed by the lowercase hex HMAC-SHA256 of the raw request body:

  • key: your endpoint's signing secret as UTF-8 bytes, the whsec_ prefix included (not hex- or base64-decoded, not stripped);
  • message: the exact bytes of the body as received.

Compare it with your own digest in constant time, before parsing the JSON. The example values are the signatures of the example bodies (in their compact form as sent) with the test secret whsec_00112233445566778899aabbccddeeff.

X-Shield-Event-Idstring

Convenience mirror of the signed body event_id. Trust the body after signature verification. Retries preserve the logical event ID.

Payload

event_type'webhook.ping' required

Event type.

schema_versionstring required

Schema version of the event type. Read event_type together with schema_version.

created_atstring date-time required

RFC 3339 timestamp in UTC with up to 9 fractional digits (trailing zeros trimmed), for example 2026-09-30T12:34:57.482913041Z. Parse it with a parser that accepts nanoseconds.

event_idstring

Example payload

{
  "schema_version": "2026-10-13",
  "created_at": "2026-09-30T12:34:57.482913041Z"
}

Response

Endpoint verified. The response body is ignored.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.