---
title: Webhooks
description: Deliver an environment's events to your HTTPS endpoint as signed
  JWTs, and verify each delivery with the published keys.
url: https://hexelstudio.com/docs/harness/webhooks
---

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:

| 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](https://hexelstudio.com/docs/harness/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:

<CodeGroup>
```ts TypeScript (Node)
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
}
```

```python Python
# 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 400
```
</CodeGroup>

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