Skip to main content
Webhooks deliver platform events to your server as signed POST requests. Subscribe in Settings → Webhooks or via the webhooks management API, give us an HTTPS URL, choose the event types you care about, and copy the signing secret.

​
Endpoint URL requirements

Your delivery URL must be a public https:// URL. Awardee rejects anything it can’t safely reach from the open internet with 400 at create time:
  • Plain http:// — TLS is required.
  • localhost and loopback addresses.
  • Private / RFC 1918 ranges (10.x, 172.16–31.x, 192.168.x).
  • Link-local and cloud-metadata addresses (169.254.x, including 169.254.169.254).
  • Bare-IP hosts — the URL must use a real hostname, not a literal IP.
These checks block SSRF and undeliverable endpoints. To test against a local server, expose it through a tunnel (ngrok, Cloudflare Tunnel) that gives you a public HTTPS hostname. See Testing.

​
Managing endpoints

You manage webhook endpoints from the dashboard or the webhooks management API. The API supports five operations:
OperationEndpoint
CreatePOST /webhooks
ListGET /webhooks
Fetch oneGET /webhooks/{id}
UpdatePATCH /webhooks/{id}
DeleteDELETE /webhooks/{id}
PATCH updates an endpoint in place — change its url, events, description, or pause/resume it with isActive — without minting a new signing secret. See Managing webhooks.

​
Visibility

Which endpoints a caller can see depends on how it authenticated:
  • API keys see every endpoint on the organization, including those created in the dashboard.
  • OAuth tokens see only the endpoints created by that same token — dashboard-managed endpoints are not visible, and one OAuth integration cannot see another’s.

​
Delivery shape

Each delivery is a POST to your URL with Content-Type: application/json. The body is the event payload directly — no wrapper envelope. Event type and delivery metadata live in headers. 
POST /webhooks/awardee HTTP/1.1
Host: api.acme.com
Content-Type: application/json
X-Awardee-Event: qr_code.scanned
X-Awardee-Delivery: 2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f
X-Awardee-Timestamp: 1716461700
X-Awardee-Signature: t=1716461700,v1=8a5f3c7e2d1b9a5c6f8e3d2c1b4a9f7e4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e

{
  "qrCodeId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "scannedAt": "2026-05-23T10:14:33Z",
  …
}
Headers
HeaderPurpose
X-Awardee-EventThe event type, e.g. qr_code.scanned. Same string you subscribed to.
X-Awardee-DeliveryUnique per delivery attempt’s parent delivery. Use it for idempotency.
X-Awardee-TimestampUnix seconds at signing time. Used by signature verification.
X-Awardee-SignatureHMAC-SHA256 signature. Format: t=<ts>,v1=<hex>. See Signing.
The payload shape varies by event type. See the Event catalog for the full list.

​
What to do on receipt

1

Verify the signature

Reject any request whose X-Awardee-Signature doesn’t match. See Signing.
2

Dedupe on X-Awardee-Delivery

The same delivery id may arrive twice (network blip, your handler crashed mid-response). Record the id; ignore repeats. See Idempotency.
3

Respond fast

Return a 2xx within 30 seconds. Queue any heavy work and acknowledge immediately. Non-2xx responses are retried.

​
Where to next

Event catalog

Every event type and its payload shape.

Signing

Verify HMAC signatures with a timing-safe compare.

Retries

Backoff schedule, ordering guarantees, and replay.

Idempotency

Dedupe on X-Awardee-Delivery so duplicates are no-ops.

Testing

Fire a test event. Receive deliveries on localhost.