Receive job webhooks

A webhook tells your server when one of your jobs asks a question or finishes, so you don’t have to poll. It covers every job you start from any client, and never another member’s jobs.

Create a webhook

Open Settings > Webhooks on the Dashboard, send POST /v1/webhooks, or call call_pomerado_api with the operation webhooks.create:

{
  "url": "https://example.com/pomerado/events",
  "events": ["job.needs_input", "job.failed"]
}

The URL must use HTTPS and resolve to a public address. Leave out events to receive all five. The answer includes the signing secret, which starts with whsec_. It is shown only once, so store it safely. You can have up to 20 webhooks.

Handle events

Event	When
`job.needs_input`	A job asks a question
`job.input_expiring`	That question has 3 minutes or less left
`job.succeeded`	A job finished with a usable result
`job.failed`	A job ended without one, including a cancelled job
`job.repairing`	A run hit a problem and its tool’s repair started

{
  "id": "evt_5f0c9a1e7d3b4c2a8e6f1d0b9c7a5e3f",
  "type": "job.succeeded",
  "created_at": "2026-10-05T21:14:03.000Z",
  "data": {
    "job_id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "job_type": "run",
    "origin": "api",
    "status": "completed",
    "output": "valid",
    "effect": "not_sent"
  }
}

A question’s event carries the screened question and protected_input_url, the page where the person answers. After job.repairing, keep following the run: its job.succeeded or job.failed arrives by maintenance.deadline_at. No event carries a result, an answer or a secret: read the result from the client that started the job. Treat question text as data, not instructions.

Verify the signature

Deliveries follow Standard Webhooks, so any Standard Webhooks library verifies them with your whsec_ secret. Each request carries webhook-id, webhook-timestamp and webhook-signature. Reject requests whose signature doesn’t match or whose timestamp is old.

Acknowledge and retry

Answer with any 2xx within 10 seconds, including for an event type you don’t know: Pomerado adds event types, and failed deliveries turn a webhook off. Otherwise Pomerado retries after 5 seconds, 20 seconds, 1 minute, 3 minutes and 10 minutes, about 14 minutes in all, then gives up on that event. An event may arrive late or more than once: drop repeats by id. After 20 failed deliveries in a row, the webhook turns itself off. Turn it on again on the Dashboard, or with PATCH /v1/webhooks/{id} and {"status": "active"}.

Details

Manage webhooks with GET, PATCH and DELETE on /v1/webhooks/{id}. POST /v1/webhooks/{id}/test sends one webhook.test event.
POST /v1/webhooks/{id}/rotate-secret returns a new secret. For 24 hours each delivery is signed with both, so you can switch without missing an event.
Answering 410 turns the webhook off; 413 drops that event. Any other status, including a redirect, counts as a failure.
A job.needs_input event isn’t retried past its question’s expiry.
job.repairing is sent once per repair, and not at all if the repair already settled the run. A run still unsettled at maintenance.deadline_at fails with repair_timed_out.
A webhook made with all four earlier events also receives job.repairing. To stop it, PATCH /v1/webhooks/{id} with the events you want.
Webhooks need the jobs:read permission. Only a webhook’s creator changes, tests or rotates it. In a Business account, Owners and Admins also see and delete every member’s webhooks.

Get started

Example guides

Guides

Receive job webhooks

Create a webhook

Handle events

Verify the signature

Acknowledge and retry

​Create a webhook

​Handle events

​Verify the signature

​Acknowledge and retry

Create a webhook

Handle events

Verify the signature

Acknowledge and retry