Webhooks
Deliver an environment's events to your HTTPS endpoint as signed JWTs, and verify each delivery with the published keys.
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.
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 JWKSDefine a webhook
PUT /harness/webhooks/{id} creates (201) or replaces (200) a webhook:
| Field | Description |
|---|---|
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). |
url | https, a public host name or address, port 443 or 1024 and up, no user info or fragment (422 invalid_url). |
event_types | Optional. 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. |
description | Optional. |
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'sid) 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:testsucceeds. Deliveries are kept for 7 days. - Success is a
2xxanswer within 10 seconds. Redirects are not followed (redirect_not_followed). - Never private. Only public addresses are dialled, checked at each connection.
last_erroris 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 newkid; 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
}# pip install "hexel-titan-harness[webhooks]"
import json
import os
import urllib.request
from titan_harness.webhooks import WebhookRefused, verify_webhook
req = urllib.request.Request(
"https://api.hexelstudio.com/v1/harness/webhook-keys",
headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
)
jwks = json.load(urllib.request.urlopen(req))
try:
delivery = verify_webhook(body, jwks, install="cloud", webhook_id="org_123/ops")
print(delivery["jti"], delivery["event"]["type"])
except WebhookRefused:
... # answer 400Cache the JWKS, and fetch it again when a delivery names a kid you do not have.