Webhooks

Sente pushes events to an HTTPS endpoint you register: inbound mail (message.received) and run state changes (run.blocked, run.completed, run.failed). Every delivery carries your organization’s webhook secret in the X-Sente-Secret header.

Register an endpoint

POST /v1/webhooks with { url, events, identityId? }. Omit identityId for an org-wide webhook; set it to scope deliveries to one identity. Registration is idempotent per (url, identity scope) — registering the same pair again does not create a duplicate.

sente webhook register --url https://your-host.example.com/sente \
  --identity <id> --events message.received,run.blocked
# → prints a "Secret:" line — store it, e.g.:
# echo "SENTE_WEBHOOK_SECRET=<the Secret: value>" >> .env

sente webhook list
sente webhook delete <webhookId>

const { secret } = await sente.webhooks.register({
  url: "https://your-host.example.com/sente",
  events: ["message.received", "run.blocked"],
  identityId: idt.id, // omit for org-wide
});
// store `secret` — webhooks.list() never returns it

await sente.webhooks.list();
await sente.webhooks.delete(webhookId);

hook = sente.webhooks.register(
    url="https://your-host.example.com/sente",
    events=["message.received", "run.blocked"],
    identity_id=idt.id,  # omit for org-wide
)
# store hook.secret — webhooks.list() never returns it

sente.webhooks.list()
sente.webhooks.delete(webhook_id)

The secret is returned at registration only — GET /v1/webhooks never includes it. It is org-level: one secret verifies every delivery to your organization, across all webhooks and identities. Store it like an API key.

URL requirements: the URL must be http(s) and resolve to a public address. Loopback, private-range (RFC 1918), link-local, and cloud-metadata addresses are rejected at registration (400) and re-checked before every delivery.

Verifying deliveries

Compare the X-Sente-Secret header against your stored secret with a timing-safe compare, then ack fast:

import { timingSafeEqual } from "node:crypto";

app.post("/sente", express.json(), async (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 fast, process after
  // ...handle req.body
});

Events

Event	When	Delivery
`message.received`	An inbound email lands in an identity’s inbox	Queued; retried with backoff. At-least-once — dedup by `message.id`.
`run.blocked`	A run parks needing a human	Single attempt, fired the instant the run blocks.
`run.completed`	A run finishes successfully	Single attempt.
`run.failed`	A run fails	Single attempt.

The run.* events are single-attempt: if your endpoint is down at that moment, the notification is lost. GET /v1/runs/:id is the backstop — poll it if you must not miss a terminal state. See the runs API reference.

`message.received`

A thin notification — it has no body. Fetch the full message (body and annotation) with GET /v1/messages/:id / sente.messages.get(id):

{
  "type": "message.received",
  "message": {
    "id": "msg_...",
    "channel": "email",
    "identity": { "id": "idt_...", "name": "support-bot", "email": "support-bot@sente.run" },
    "from": "user@example.com",
    "to": "support-bot@sente.run",
    "subject": "hi",
    "createdAt": "2026-07-01T12:00:00.000Z"
  }
}

`run.blocked`

Fired when a register, login, or connect run needs a human — a CAPTCHA, an SMS/phone step, a payment step, a confirm-before-submit pause, or an MFA code only the account owner can receive. The payload carries everything needed to route a person to the gate:

{
  "type": "run.blocked",
  "run": {
    "id": "run_...",
    "type": "register",
    "status": "blocked",
    "code": "SUBMIT_CONFIRMATION_REQUIRED",
    "detail": "...",
    "confirmBeforeSubmit": true,
    "registrationId": "reg_...",
    "appUrl": "https://app.example.com",
    "identity": { "id": "idt_...", "name": "...", "email": "...@sente.run" },
    "liveViewUrl": "https://...",
    "actionUrl": "https://app.sente.run/runs/run_...",
    "holdExpiresAt": "2026-07-01T12:10:00.000Z",
    "createdAt": "2026-07-01T12:00:00.000Z"
  }
}

code — why the run blocked: SUBMIT_CONFIRMATION_REQUIRED, CAPTCHA_REQUIRED, MISSING_FIELD, PAYMENT_REQUIRED, PHONE_REQUIRED, LOGIN_UNCONFIRMED, or (connect runs) TOTP_REQUIRED / MFA_REQUIRED.
liveViewUrl — the interactive browser view where a person clears the step.
actionUrl — a dashboard deep link to the run page (live view, submit, and resume in one place).
holdExpiresAt — the run holds for roughly 10 minutes, then auto-fails with BLOCKED_TIMEOUT if not resumed. A notification should tell the human how long they have.

Not fired for a user-initiated pause (manual intervention from the dashboard) — the user already knows. See Runs and human takeover for the block/resume flow.

`run.completed` / `run.failed`

{
  "type": "run.completed",
  "run": {
    "id": "run_...",
    "type": "register",
    "status": "completed",
    "code": null,
    "detail": null,
    "registrationId": "reg_...",
    "appUrl": "https://app.example.com",
    "identity": { "id": "idt_...", "name": "...", "email": "...@sente.run" },
    "result": { "...": "..." },
    "createdAt": "2026-07-01T12:00:00.000Z",
    "endedAt": "2026-07-01T12:03:00.000Z"
  }
}

run.failed is the same shape with status: "failed", the error code/detail set, and result: null.

Desktop notifications without a webhook

sente watch is the pull-based counterpart for a human at a machine — a daemon that polls and fires an OS desktop notification the moment any run blocks, with the live-view URL and the sente run resume <id> command:

sente watch                    # all identities
sente watch --identity <ref> --interval 5

Testing locally

No public URL needed during development — the CLI relays inbound mail to a local handler with the exact same payload and X-Sente-Secret header:

SENTE_WEBHOOK_SECRET=<your-secret> sente listen --identity <id> --forward http://localhost:3000/sente

Get started

Core concepts

Guides

Trust

Register an endpoint

Verifying deliveries

Events

`message.received`

`run.blocked`

`run.completed` / `run.failed`

Desktop notifications without a webhook

Testing locally

​Register an endpoint

​Verifying deliveries

​Events

​message.received

​run.blocked

​run.completed / run.failed

​Desktop notifications without a webhook

​Testing locally

Register an endpoint

Verifying deliveries

Events

`message.received`

`run.blocked`

`run.completed` / `run.failed`

Desktop notifications without a webhook

Testing locally