Webhooks
Updated 2026-10-16
If you start a run with webhook, Jinn sends the events of the run to that HTTPS address.
The body of each request is one event:
{
"id": "evt_eb3b996c374758cb45d428f2",
"type": "run.succeeded",
"created": "2026-10-14T10:04:54.518561346Z",
"sequence": 15,
"data": {"id": "run_eb3b996c374758cb45d428f2", "state": "succeeded", "output": {"url": "https://…", "file_count": 2, "bytes": 573, "files": […]}, …}
}
type | Jinn sends it when | data |
|---|---|---|
run.running | The run is ready. Setup is complete, and commands can run. | The run |
run.maintenance | Jinn must replace the machine of the run. maintenance_at gives the time when the run will end with maintenance. | The run |
run.succeeded | The run succeeded. | The run |
run.failed | The run failed. | The run |
command.finished | A command that you sent ended. The commands of the agent do not send this event. | The command |
data is the run, as GET /v1/runs/{id} returns it. Or data is the command, as GET /v1/runs/{id}/commands/{cid} returns it. sequence is the sequence of the run at the time of the change. You can receive events out of sequence. Use sequence to put them in sequence.
Delivery
- Answer with a
2xxstatus in 10 seconds or less. - Jinn makes five attempts, 3 minutes apart. Then it stops. If you did not receive an event, read the run. You can also read its commands from a sequence.
- Jinn sends events only to public HTTPS addresses. It does not follow redirects.
- All attempts have the same
webhook-id. Use it to ignore an event that you received before.
Verify the signature
Webhooks use Standard Webhooks with Ed25519 signatures (v1a). Each account has its own key. The Account page of the console shows its public key (whpk_…). GET /v1/webhooks/public-key also returns it.
| Header | Value |
|---|---|
webhook-id | The id of the event. |
webhook-timestamp | The time of the signature, in Unix seconds. |
webhook-signature | v1a, and the base64 Ed25519 signature of {webhook-id}.{webhook-timestamp}.{body}. |
Refuse the request if the signature is not correct. Also refuse it if the timestamp is more than 5 minutes from the current time.
Go:
event, err := jinn.VerifyWebhook(publicKey, r.Header, body, time.Now())
TypeScript:
const event = await verifyWebhook(publicKey, request.headers, await request.text());
Python, with cryptography:
import base64
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
key = Ed25519PublicKey.from_public_bytes(base64.b64decode(public_key.removeprefix("whpk_")))
signed = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.{body}".encode()
signature = base64.b64decode(headers["webhook-signature"].split(",", 1)[1])
key.verify(signature, signed) # raises InvalidSignature