Webhooks

Webhooks deliver events to your server the moment they happen, so you do not have to poll. Each delivery is a JSON POST to a URL you register, signed with HMAC-SHA256 so you can verify it came from us.

Our envelope and signature scheme implement the Standard Webhooks specification. Any verifier from that ecosystem will work out of the box.

Quickstart

1. Register an endpoint

Register from the dashboard at Organization → Webhooks. You supply the destination URL and pick the event types you want delivered. There is no wildcard, so subscribers opt in to each event type explicitly.

After creation you receive a signing secret of the form whsec_…. Store it immediately. It is not retrievable later. If you lose it, rotate it.

Programmatic management of endpoints (create, list, update, delete) is available in the API reference.

2. Receive a delivery

Every delivery is a POST to your registered URL with this envelope:

1
{
2
  "id": "msg_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
3
  "type": "elp_test.scored",
4
  "timestamp": "2026-05-26T19:33:42Z",
5
  "data": {
6
    "id": "elp_550e8400-e29b-41d4-a716-446655440000",
7
    "status": "COMPLETED",
8
    "scoring_status": "SCORED",
9
    "...": "full ELP test response"
10
  }
11
}

Three signing headers travel with the body:

Always respond with a 2xx within 15 seconds. Anything else is treated as a delivery failure and triggers a retry.

3. Verify the signature

Use the official Standard Webhooks library for your language. The verifier takes your whsec_… secret plus the request body and the three webhook-* headers, and tells you whether the signature is valid.

Python (standardwebhooks on PyPI):

1
from standardwebhooks import Webhook
2
3
wh = Webhook(signing_secret)              # "whsec_..."
4
payload = wh.verify(request_body, request_headers)  # raises on failure

TypeScript / Node (standardwebhooks on npm):

1
import { Webhook } from "standardwebhooks";
2
3
const wh = new Webhook(signingSecret);    // "whsec_..."
4
const payload = wh.verify(requestBody, requestHeaders); // throws on failure

For any other language (Go, Ruby, PHP, Rust, Java, .NET, and more), pick the official SDK from standardwebhooks.com/#sdks. All follow the same interface: hand it the secret, body, and headers; get back the verified payload or an error.

Idempotency

webhook-id is stable across retries. If the same webhook-id arrives twice, it is the same logical event. Process once, ignore the rest.

on_webhook(headers, body):
    msg_id = headers["webhook-id"]
    if seen(msg_id):
        return 200  # already processed; ack so we stop retrying
    process(body)
    record_seen(msg_id)
    return 200

Retries are exponential with jitter. We retry on any non-2xx response or connection failure for up to ~24 hours, then give up. Every attempt is captured in the per-endpoint delivery log at Organization → Webhooks → {endpoint}. Expand a row to see the request payload and response. Failed and dead deliveries can be replayed from there.

Secret rotation

Rotate from the dashboard at Organization → Webhooks. Pick the endpoint row and select Rotate secret.

Rotation mints a fresh whsec_… secret and keeps the previous one valid for 24 hours. During the overlap window, webhook-signature includes one v1,<sig> per active secret, so verification with either succeeds. Update your stored secret to the new value any time within those 24 hours.

Reserved headers

webhook-id, webhook-timestamp, and webhook-signature are always set by us. If you configure custom headers on your endpoint that collide with these names, the custom values are silently dropped at delivery time. That prevents an endpoint from being tricked into signing its own deliveries.

Event catalog

The authoritative list of subscribable event types lives in the API reference.

Next steps

• ELP Tests. Worked example using elp_test.scored.
• Standard Webhooks spec. The underlying signing and envelope contract.