Webhooks - Sente

Webhooks push events to your HTTPS endpoint so your agent reacts to inbound mail and to runs that need a human — without polling. The one you almost certainly want is run.blocked: a run that stops for a CAPTCHA, an SMS code, or a final submit is held for ten minutes, and this is how someone finds out in time.

Events

Event	Fires when	Retries
`message.received`	An inbound email lands in an identity’s inbox, after it has been classified.	Queued. Retried if every subscribed endpoint failed; a partial success is accepted and not retried.
`run.blocked`	A run pauses for a human.	None — single attempt.
`run.completed`	A run finishes successfully.	None — single attempt.
`run.failed`	A run fails, including abort and timeout.	None — single attempt.

The run.* events are delivered once, with no retry. If your endpoint can miss a delivery, pair them with polling GET /v1/runs/:id — or, for blocked runs, rely on the operator email that Sente also sends. Never make a run.* webhook the only thing standing between a blocked run and its ten-minute hold expiring.

Delivery

Each delivery is an HTTP POST with content-type: application/json and a 10-second timeout. Every delivery to your org carries the org-level secret in the x-sente-secret header:

POST /your/endpoint HTTP/1.1
content-type: application/json
x-sente-secret: whsec_k3v9...

Verify it with a constant-time compare before trusting the payload. There is no HMAC over the body and no raw-body requirement — a plain parsed-JSON handler is enough.

import { timingSafeEqual } from "node:crypto";

app.post("/sente/events", (req, res) => {
  const got = Buffer.from(req.header("x-sente-secret") ?? "");
  const want = Buffer.from(process.env.SENTE_WEBHOOK_SECRET!);
  if (got.length !== want.length || !timingSafeEqual(got, want)) return res.sendStatus(401);

  res.sendStatus(200); // ack first, then do the work
  handle(req.body);
});

Any non-2xx response — or a timeout — records the delivery as failed. Respond fast and do the work afterwards.

Webhook URLs must be http(s) and must resolve to a public address. URLs pointing at loopback, private ranges, link-local, or cloud-metadata addresses are rejected at registration with 400, and re-checked immediately before every delivery in case DNS changed in between.

Create a webhook

POST /v1/webhooks

Field	Type	Required	Description
`url`	URL	yes	Your endpoint. Must resolve to a public address.
`events`	array	yes	At least one of `message.received`, `run.completed`, `run.failed`, `run.blocked`. Unknown values are rejected.
`identityId`	string	no	Scope to one identity. Omitted → fires for every identity in the org, including ones auto-provisioned later.

Idempotent per (url, identity scope): re-posting the same url and scope returns the existing subscription with its event list replaced by the one you sent. Safe to call on every app start — and note that it replaces rather than merges, so always send the full list.

curl -X POST https://api.sente.run/v1/webhooks \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{
    "url": "https://agent.example.com/sente/events",
    "events": ["message.received", "run.blocked", "run.completed", "run.failed"]
  }'

sente webhook register \
  --url https://agent.example.com/sente/events \
  --events message.received,run.blocked,run.completed,run.failed

import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_KEY! });

const hook = await sente.webhooks.register({
  url: "https://agent.example.com/sente/events",
  events: ["message.received", "run.blocked", "run.completed", "run.failed"],
});
console.log(hook.secret); // store it — verify every delivery against this

import os
from sente import Sente

sente = Sente(api_key=os.environ["SENTE_API_KEY"])

hook = sente.webhooks.register(
    url="https://agent.example.com/sente/events",
    events=["message.received", "run.blocked", "run.completed", "run.failed"],
)
print(hook.secret)  # store it — verify every delivery against this

Response 201 — the only response in the API that contains the secret:

{
  "id": "whk_4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
  "url": "https://agent.example.com/sente/events",
  "events": ["message.received", "run.blocked", "run.completed", "run.failed"],
  "identityId": null,
  "secret": "whsec_k3v9m2q8..."
}

The secret is org-level, not per-webhook: every delivery to your org carries the same one, so a second subscription returns the same value.

Status	Body	What to do
`400`	zod issues	An unknown event name, an empty `events` array, or a `url` that isn’t a URL.
`400`	`{"error": "webhook url not allowed: ..."}`	The URL resolves to a private, loopback, link-local, or metadata address. Expose a public endpoint, or use a tunnel that has a public hostname.
`404`	`{"error": "identity not found"}`	`identityId` isn’t your org’s.

List webhooks

GET /v1/webhooks

curl https://api.sente.run/v1/webhooks \
  -H "Authorization: Bearer sk_sente_..."

Response 200 — no secret in list responses:

[
  {
    "id": "whk_4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
    "url": "https://agent.example.com/sente/events",
    "events": ["message.received", "run.blocked", "run.completed", "run.failed"],
    "identityId": null,
    "createdAt": "2026-07-20T09:00:00.000Z"
  }
]

Lost the secret? Re-post the same url and scope to POST /v1/webhooks — the response returns the org secret again, and the existing subscription is reused rather than duplicated.

Delete a webhook

DELETE /v1/webhooks/:id

curl -X DELETE https://api.sente.run/v1/webhooks/whk_4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d \
  -H "Authorization: Bearer sk_sente_..."

Response: 204 with no body. 404 {"error": "not found"} for an unknown id or another org’s subscription.

Payloads

message.received

{
  "type": "message.received",
  "message": {
    "id": "msg_5b0e8d7c6f5a4e3d2c1b0a9f8e7d6c5b",
    "channel": "email",
    "identity": { "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5", "name": "support-agent", "email": "acme-qa@sente.run" },
    "from": "no-reply@example-app.com",
    "to": "acme-qa@sente.run",
    "subject": "Your verification code",
    "createdAt": "2026-07-20T09:15:02.114Z"
  }
}

A summary only — the body and the extracted code are not in the payload. Fetch them with GET /v1/messages/:id. channel is always email today.

run.blocked

Fired the moment a run parks for a human, and carrying everything a notifier needs to route someone to the gate:

{
  "type": "run.blocked",
  "run": {
    "id": "run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
    "type": "register",
    "status": "blocked",
    "code": "CAPTCHA_REQUIRED",
    "detail": "captcha on the signup form",
    "confirmBeforeSubmit": false,
    "registrationId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "appUrl": "https://app.example.com/signup",
    "identity": { "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5", "name": "support-agent", "email": "acme-qa@sente.run" },
    "liveViewUrl": "https://app.hyperbrowser.ai/live?...",
    "actionUrl": "https://app.sente.run/runs/run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
    "holdExpiresAt": "2026-07-20T11:15:00.000Z",
    "createdAt": "2026-07-20T11:00:00.000Z"
  }
}

Field	Why you care
`code`	Why it stopped — the blocked codes. Decides whether a human is even needed (`PAYMENT_REQUIRED` usually means abort).
`actionUrl`	Dashboard deep link: live view, submit, and resume in one page. Put this in the notification.
`liveViewUrl`	The raw interactive browser, if you’d rather embed it yourself.
`holdExpiresAt`	When the run auto-fails `BLOCKED_TIMEOUT`. Say it in the notification so the human knows the deadline.

Every blocked run also emails the org’s operators the same dashboard link, using each user’s notification preference. The webhook is for your systems; the email is the “you walked away” backstop. The sente watch CLI command is a third path — a desktop notifier.

run.completed / run.failed

{
  "type": "run.completed",
  "run": {
    "id": "run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
    "type": "register",
    "status": "completed",
    "code": null,
    "detail": null,
    "registrationId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "appUrl": "https://app.example.com/signup",
    "identity": { "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5", "name": "support-agent", "email": "acme-qa@sente.run" },
    "result": { "answer": "STATE: LOGGED_IN" },
    "createdAt": "2026-07-20T11:00:00.000Z",
    "endedAt": "2026-07-20T11:03:12.500Z"
  }
}

run.failed has the same shape with "status": "failed", the failure code in code/detail, and "result": null. Both fire exactly once, from whichever writer wins the terminal transition — including the timeout and worker-recovery paths, so a run that dies quietly still notifies. appUrl is null when the run has no registration behind it. Note that the run payloads use code/detail at the top level, where the run object from GET /v1/runs/:id nests them under error.

Webhooks guide

Endpoint setup, verification, and retries in practice.

Human takeover

What to do when run.blocked arrives.

Messages

Fetch the body after message.received.

​Events

​Delivery

​Create a webhook

​List webhooks

​Delete a webhook

​Payloads

​message.received

​run.blocked

​run.completed / run.failed

​Related

Webhooks guide

Human takeover

Messages

Events

Delivery

Create a webhook

List webhooks

Delete a webhook

Payloads

message.received

run.blocked

run.completed / run.failed

Related