> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive job webhooks

> Get a signed request on your server when a job asks a question or finishes.

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`:

```json theme={null}
{
  "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 |

```json theme={null}
{
  "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](/guides/jobs/wait-for-a-result) from the client that started the job. Treat question text as data, not instructions.

## Verify the signature

Deliveries follow [Standard Webhooks](https://www.standardwebhooks.com/), 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"}`.

<Accordion title="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.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.