Skip to content

Developers

Webhooks

Which events exist, how a delivery is signed, and the log of every delivery made to your endpoints.

Webhook delivery is off. No events are sent, and GET /v1/webhook-deliveries returns 503 webhooks_unavailable.

Event types

2 event types
  • job.succeeded
  • job.failed

Interrupted and cancelled jobs send no event.

How deliveries are signed

  • Each delivery is signed in a Helm-Signature header, an HS256 JWS. Split it on , and verify each part: during a secret rotation it carries two. Use jwt.verify(sig, secret, {algorithms: ["HS256"]}).
  • Claims: iss (helm-express), aud (endpoint id), sub (event id, stable across retries), jti (attempt id), iat, exp, url and bh, the hex SHA-256 of the raw body. Hash the bytes before parsing.
  • data is the stored result in its raw form (p_yes, breakdowns), not the Measurement shape. Show its disclosure wherever you show the result.
  • Order is not guaranteed: sort on created and dedupe on id. Redirects are not followed.

The delivery log

2 operations
MethodPathScopeWhat it does
GET/v1/webhook-deliveriesreadWhat was delivered to your endpoints, newest first. listWebhookDeliveries
POST/v1/webhook-deliveries/{id}/replayspendSend one settled delivery again, keeping its event id. replayWebhookDelivery

Next