Jinn docs Console

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": […]}, …}
}
typeJinn sends it whendata
run.runningThe run is ready. Setup is complete, and commands can run.The run
run.maintenanceJinn must replace the machine of the run. maintenance_at gives the time when the run will end with maintenance.The run
run.succeededThe run succeeded.The run
run.failedThe run failed.The run
command.finishedA 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

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.

HeaderValue
webhook-idThe id of the event.
webhook-timestampThe time of the signature, in Unix seconds.
webhook-signaturev1a, 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