Skip to content
Hexel StudioDocs

Webhooks

Deliver an environment's events to your HTTPS endpoint as signed JWTs, and verify each delivery with the published keys.

On this page

A webhook delivers the environment's events to your HTTPS endpoint. Each delivery is signed with Hexel Studio's webhook key, so your endpoint can check where it came from; there is no shared secret.

Bash
hexel harness webhook set ops --url https://ops.example.com/hooks/harness --event-type "task.*"
hexel harness webhook test ops
hexel harness webhook list
hexel harness webhook keys          # the public keys, as a JWKS

Define a webhook

PUT /harness/webhooks/{id} creates (201) or replaces (200) a webhook:

FieldDescription
id (path)1 to 64 of A-Z a-z 0-9 _ -, unique in your organization. An id used in one environment cannot be reused in another, even after a delete (409 webhook_id_taken).
urlhttps, a public host name or address, port 443 or 1024 and up, no user info or fragment (422 invalid_url).
event_typesOptional. Exact types or a family such as task.*; empty or * is every type. A type added to the harness later is not sent until you replace the webhook.
descriptionOptional.

GET /harness/webhooks shows each webhook's audience, its state (active or failing), the last attempt's last_status and last_error, and pending_deliveries. An environment can have up to 20 webhooks. Managing webhooks needs harness:webhook:manage (Admins and Owners).

POST /harness/webhooks/{id}:test signs and sends one webhook.test event now (at most one every 5 seconds per webhook, and 10 a minute per organization).

What is delivered

Every event type in Events except message, and agent.promoted. Deliveries carry metadata only: ids, states, resource names, numbers and digests. A field that is too large or of the wrong kind is left out and named in data.omitted.

Delivery

  • At least once. Use the delivery's jti (the event's id) to drop duplicates.
  • Retries after 1 second, 10 seconds, 1 minute, 10 minutes, 1 hour and 6 hours. Then the delivery fails and the webhook becomes failing: its deliveries are held until you replace it or a :test succeeds. Deliveries are kept for 7 days.
  • Success is a 2xx answer within 10 seconds. Redirects are not followed (redirect_not_followed).
  • Never private. Only public addresses are dialled, checked at each connection. last_error is a fixed code (timeout, tls_error, connection_error, invalid_url, redirect_not_followed, http_<status>), never your endpoint's body.

Verify a delivery

A delivery is a POST with Content-Type: application/jwt: a compact JWS.

  • Header, exactly: {"alg": "EdDSA", "kid": "<key id>", "typ": "harness-event+jwt"}.
  • Payload, exactly these six fields: {"v": 1, "iss": "urn:hexel:harness:cloud", "aud": "<org_id>/<webhook id>", "iat": <unix seconds>, "jti": "<event id>", "event": <the event>}.
  • Keys: the public keys are a JWKS at https://api.hexelstudio.com/v1/harness/webhook-keys. The route needs no harness permission, but the API gateway requires an access token: send one for your organization. Keys rotate with a new kid; old public keys stay published.

Refuse a delivery unless the header is exactly as above with a kid in the JWKS, the Ed25519 signature verifies, the payload has exactly those six fields with v equal to 1, iss is urn:hexel:harness:cloud, aud is your webhook's audience, your clock is within iat - 60s and iat + 360s, and event.id equals jti.

The SDKs do all of these checks:

import { verifyWebhook, WebhookRefused } from "@hexelstudio/titan-harness/webhooks"

const jwks = await (
  await fetch("https://api.hexelstudio.com/v1/harness/webhook-keys", {
    headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}` },
  })
).json()

// body: the raw request body, as a string
try {
  const delivery = verifyWebhook(body, jwks, { install: "cloud", webhookId: "org_123/ops" })
  console.log(delivery.jti, delivery.event.type)
} catch (err) {
  if (err instanceof WebhookRefused) { /* answer 400 */ }
  throw err
}

Cache the JWKS, and fetch it again when a delivery names a kid you do not have.