# Webhooks

Monitor webhooks and workspace webhook endpoints, the connection events, every delivery's attempt log, verifying the PrimaryAPI-Signature header in Node and Python, retries, redelivery, how long events are kept, and the signing secret.

PrimaryAPI sends webhooks from two places:

- **Monitors.** A [monitor](/docs/monitors) sends its results to its own webhook URL.
- **Webhook endpoints.** URLs your workspace registers to hear about its [connected accounts](/docs/connected-accounts): an account was connected, needs reconnecting or was disconnected, or a customer invite expired.

Both arrive as `POST` requests with a JSON body, signed with your workspace's one signing secret, retried on the same schedule, and logged attempt by attempt. Verify both the same way.

## Monitor events

```http title="POST https://example.com/hooks/primaryapi"
Content-Type: application/json
User-Agent: PrimaryAPI-Webhooks/1.0
PrimaryAPI-Signature: t=1762689600,v1=5f2a…c41e
PrimaryAPI-Event-Id: evt_01jc8t3a0c2e4g6j8m0p2r4t6w
PrimaryAPI-Event-Type: monitor.run.succeeded
PrimaryAPI-Delivery-Id: whd_01jc8t3a0d4f6h8k0m2p4r6t8x
PrimaryAPI-Delivery-Attempt: 1

{
  "id": "evt_01jc8t3a0c2e4g6j8m0p2r4t6w",
  "type": "monitor.run.succeeded",
  "createdAt": "2026-11-09T12:00:01.204Z",
  "monitor": {
    "id": "mon_01jc8t2v6x0d4f6h8k0m2p4r6t",
    "customId": "crm-account-1042",
    "name": null,
    "sku": "instagram.profile"
  },
  "run": {
    "id": "mrun_01jc8t39yb1d3f5h7k9m1p3r5t",
    "requestId": "req_01jc8t39yc3e5g7j9m1p3r5t7v",
    "status": "succeeded",
    "reason": null,
    "changed": true,
    "credits": 3,
    "items": 1,
    "createdAt": "2026-11-09T12:00:00.012Z"
  },
  "output": {
    "found": true,
    "data": { "username": "natgeo", "followers": 283104512, "…": "…" }
  },
  "connection": null
}
```

| `type` | Sent when | `run` | `output` |
|---|---|---|---|
| `monitor.run.succeeded` | A run succeeded and the monitor notifies for it: the first result and every change with `notify: "change"`, every result with `notify: "always"` | the run | the API's output (`found`, `data`, `reason`), exactly as in the [run envelope](/docs/making-requests) |
| `monitor.run.failed` | A run failed, while the monitor's `notifyFailures` is on | the run, with `reason` | `null` |
| `monitor.test` | You asked for a test event | `null` | `null` |

`monitor.customId` is your own reference, so you can match the event to your record without storing our ids. `run.requestId` is the call the run made, the same id as in your request history.

`connection` is `null` unless the monitor reads a [connected account](/docs/monitors#monitor-a-connected-account). Then it names that account as it was when the event was made: `{ "id", "provider", "label", "name", "customId", "status" }`. A run that failed because the account must be reconnected has `run.reason` `connection_needs_reauth` and `connection.status` `needs_reauth`.

`monitorPaused` appears on one event only: the `monitor.run.failed` of the run that made us pause the monitor, the 10th failed run in a row ([When runs keep failing](/docs/monitors#when-runs-keep-failing)). Every other event leaves it out, so treat a missing field as "not paused".

```json title="The failure event that paused the monitor (excerpt)"
{
  "type": "monitor.run.failed",
  "run": { "status": "failed", "reason": "all_sources_failed", "…": "…" },
  "output": null,
  "monitorPaused": {
    "reason": "failing",
    "failingSince": "2026-11-05T09:00:00.000Z",
    "consecutiveFailures": 10
  }
}
```

`failingSince` is when the failures began, and `consecutiveFailures` how many runs in a row failed. The monitor stays paused until you resume it. With `notifyFailures` off no failure event is sent, but the monitor is still paused. When the 10th failure is a webhook that was never delivered (your endpoint didn't answer through every retry), there is no event to carry the pause: it shows on the monitor, in the dashboard and in the API.

## Webhook endpoints

A webhook endpoint hears about your workspace's connected accounts, so your own product can update its records without polling: a customer connected their account through your invite, an account needs reconnecting, an account was disconnected, an invite expired unused. Add endpoints in the dashboard under **Settings › Webhooks**, or with the API.

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/primaryapi-accounts", "description": "CRM sync", "events": ["connection.connected", "connection.disconnected"] }'
```

**201 Created**:

```json
{
  "id": "whe_01jd3k6v2m4p6r8t0w2y4a6c8e",
  "url": "https://example.com/hooks/primaryapi-accounts",
  "description": "CRM sync",
  "events": ["connection.connected", "connection.disconnected"],
  "status": "active",
  "createdAt": "2026-11-12T10:00:00.000Z",
  "updatedAt": "2026-11-12T10:00:00.000Z",
  "lastDeliveryStatus": null,
  "lastDeliveryAt": null
}
```

- **Events.** Leave `events` out to hear every event type. Send at least one when you set it.
- **URL.** The same rules as a monitor's webhook URL: `https://`, a public host, no user name or password in it. Private, local and internal addresses are refused when you save it (`400 invalid_input`) and again on every attempt.
- **Limit.** A workspace keeps at most 10 endpoints. The 11th answers `422 unprocessable` with `details.reason: "endpoint_limit"`. One endpoint can hear every event type.
- **Disable.** A disabled endpoint (`"status": "disabled"`) gets no new events. Deliveries already waiting for a retry still finish.
- **Change the URL.** A new URL also applies to the deliveries still waiting for a retry, so fixing a wrong URL fixes those too.
- **Delete.** Deleting an endpoint gives up its waiting retries and deletes its deliveries with their attempt logs.
- **Who.** Owners and admins in the dashboard, or an API key with `full` access. Every other role and key gets `403 forbidden`, reads included.

`GET https://api.primaryapi.com/v1/webhook-endpoints`

Auth: API key with full access, or a dashboard session (owners and admins)

The workspace's endpoints, oldest first: `{ "items": [<endpoint>, …] }`. `lastDeliveryStatus` and `lastDeliveryAt` are the newest delivery's status and when it was made.

`POST https://api.primaryapi.com/v1/webhook-endpoints`

Auth: API key with full access, or a dashboard session (owners and admins)

Adds an endpoint: `url` (required), `description` (1 to 200 characters) and `events`. **201 Created**: the endpoint.

`GET https://api.primaryapi.com/v1/webhook-endpoints/{id}`

Auth: API key with full access, or a dashboard session (owners and admins)

One endpoint. `404 not_found` for an unknown id or one of another workspace.

`PATCH https://api.primaryapi.com/v1/webhook-endpoints/{id}`

Auth: API key with full access, or a dashboard session (owners and admins)

Send only what changes: `url`, `description` (`null` clears it), `events`, `status` (`active` or `disabled`). **200 OK**: the endpoint.

`DELETE https://api.primaryapi.com/v1/webhook-endpoints/{id}`

Auth: API key with full access, or a dashboard session (owners and admins)

**200 OK**: `{ "id": "whe_…", "deleted": true }`.

`POST https://api.primaryapi.com/v1/webhook-endpoints/{id}/test`

Auth: API key with full access, or a dashboard session (owners and admins)

Sends a `webhook_endpoint.test` event to this endpoint only, disabled ones too, to check your endpoint and your signature check. It is free. **201 Created**: the delivery after its first attempt. A failed test is retried like any delivery.

`GET https://api.primaryapi.com/v1/webhook-endpoints/{id}/deliveries`

Auth: API key with full access, or a dashboard session (owners and admins)

The endpoint's deliveries, newest first (`limit`, `cursor`): `{ "items": […], "nextCursor": … }`. Fields: `id` (`whd_…`), `endpointId`, `eventId`, `eventType`, `url`, `status` (`pending`, `retrying`, `succeeded`, `failed`), `attempts`, `nextAttemptAt`, `lastResponseStatus`, `lastError`, `createdAt` and `deliveredAt`.

`GET https://api.primaryapi.com/v1/webhook-endpoints/{id}/deliveries/{deliveryId}`

Auth: API key with full access, or a dashboard session (owners and admins)

One delivery with its `attemptLog` ([The attempt log](#the-attempt-log)) and `event`: the body as sent, while it is kept ([How long events are kept](#how-long-events-are-kept)), then `null`.

`POST https://api.primaryapi.com/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/redeliver`

Auth: API key with full access, or a dashboard session (owners and admins)

A new delivery of the same event to the endpoint's current URL ([Redeliver](#redeliver)). **201 Created**: the new delivery after its first attempt.

Test events and redeliveries are capped together at 60 per minute per workspace, for endpoints and monitors each (`429 rate_limited`).

## Connection events

Every endpoint event has the same envelope: `id`, `type`, `createdAt`, `workspaceId` and `data`. The headers are the same as for monitor events, with the event's type in `PrimaryAPI-Event-Type`.

| `type` | Sent when | `data` |
|---|---|---|
| `connection.connected` | An account was connected: by a member in the dashboard, through an agent's connect link, or by a customer through an invite. Also when the same account is connected again. | `connection`, `reconnected`, and `invite` when it came through one |
| `connection.needs_reauth` | An account's access expired or was revoked at the provider. Calls on it fail until it's reconnected. | `connection` |
| `connection.disconnected` | An account was disconnected in PrimaryAPI. Its monitors were deleted with it. | `connection`, `deletedMonitorIds` |
| `connection.invite_expired` | A customer invite expired without being used. | `invite` |
| `webhook_endpoint.test` | You asked for a test event. | `{}` |

`connection` is the account as it is when the event is made: `id`, `provider`, `label` (the account's handle at the provider), `name`, `customId`, `status` (`active`, `needs_reauth` or `revoked`), `capabilities`, `connectedVia` (`member`, `link` or `invite`) and `inviteId`. `invite` is `id`, `provider`, `name`, `customId`, `capabilities` and `expiresAt`. Events say who, what and when only: never tokens, scopes or anything read from the account.

```json title="connection.connected, a customer through an invite"
{
  "id": "evt_01jd3m2a7c9e1g3j5m7p9r1t3v",
  "type": "connection.connected",
  "createdAt": "2026-11-12T10:14:03.511Z",
  "workspaceId": "acc_01jd2x7d3f5h7k9m1p3r5t7v9x",
  "data": {
    "connection": {
      "id": "con_01jd3m29zq8s0u2w4y6a8c0e2g",
      "provider": "instagram",
      "label": "@acmebakery",
      "name": "Acme Bakery",
      "customId": "cust_1042",
      "status": "active",
      "capabilities": ["profile", "insights"],
      "connectedVia": "invite",
      "inviteId": "cin_01jd3k8b4d6f8h0k2m4p6r8t0w"
    },
    "invite": {
      "id": "cin_01jd3k8b4d6f8h0k2m4p6r8t0w",
      "provider": "instagram",
      "name": "Acme Bakery",
      "customId": "cust_1042",
      "capabilities": ["profile", "insights"],
      "expiresAt": "2026-11-19T10:00:00.000Z"
    },
    "reconnected": false
  }
}
```

```json title="connection.connected, a member in the dashboard"
{
  "id": "evt_01jd3p0c2e4g6j8m0p2r4t6w8y",
  "type": "connection.connected",
  "createdAt": "2026-11-12T11:02:44.090Z",
  "workspaceId": "acc_01jd2x7d3f5h7k9m1p3r5t7v9x",
  "data": {
    "connection": {
      "id": "con_01jd3p0b0d2f4h6k8m0p2r4t6v",
      "provider": "github",
      "label": "octo-dev",
      "name": null,
      "customId": null,
      "status": "active",
      "capabilities": ["profile", "repos_read"],
      "connectedVia": "member",
      "inviteId": null
    },
    "reconnected": true
  }
}
```

`reconnected` is `true` when the same account was connected to the workspace before: a reconnect, or a new invite for an account you already had.

```json title="connection.needs_reauth"
{
  "id": "evt_01jd4a1b3d5f7h9k1m3p5r7t9v",
  "type": "connection.needs_reauth",
  "createdAt": "2026-11-13T08:30:00.000Z",
  "workspaceId": "acc_01jd2x7d3f5h7k9m1p3r5t7v9x",
  "data": {
    "connection": {
      "id": "con_01jd3m29zq8s0u2w4y6a8c0e2g",
      "provider": "instagram",
      "label": "@acmebakery",
      "name": "Acme Bakery",
      "customId": "cust_1042",
      "status": "needs_reauth",
      "capabilities": ["profile", "insights"],
      "connectedVia": "invite",
      "inviteId": "cin_01jd3k8b4d6f8h0k2m4p6r8t0w"
    }
  }
}
```

```json title="connection.disconnected"
{
  "id": "evt_01jd4c6e8g0j2m4p6r8t0w2y4a",
  "type": "connection.disconnected",
  "createdAt": "2026-11-14T16:45:12.300Z",
  "workspaceId": "acc_01jd2x7d3f5h7k9m1p3r5t7v9x",
  "data": {
    "connection": {
      "id": "con_01jd3m29zq8s0u2w4y6a8c0e2g",
      "provider": "instagram",
      "label": "@acmebakery",
      "name": "Acme Bakery",
      "customId": "cust_1042",
      "status": "revoked",
      "capabilities": ["profile", "insights"],
      "connectedVia": "invite",
      "inviteId": "cin_01jd3k8b4d6f8h0k2m4p6r8t0w"
    },
    "deletedMonitorIds": ["mon_01jd3q4s6u8w0y2a4c6e8g0j2m"]
  }
}
```

```json title="connection.invite_expired"
{
  "id": "evt_01jd5e0g2j4m6p8r0t2w4y6a8c",
  "type": "connection.invite_expired",
  "createdAt": "2026-11-19T10:01:00.412Z",
  "workspaceId": "acc_01jd2x7d3f5h7k9m1p3r5t7v9x",
  "data": {
    "invite": {
      "id": "cin_01jd3k9c5e7g9j1m3p5r7t9v1x",
      "provider": "google",
      "name": "Orchard Accounting",
      "customId": "cust_1170",
      "capabilities": ["profile", "calendar_read"],
      "expiresAt": "2026-11-19T10:00:00.000Z"
    }
  }
}
```

```json title="webhook_endpoint.test"
{
  "id": "evt_01jd3k7a3c5e7g9j1m3p5r7t9v",
  "type": "webhook_endpoint.test",
  "createdAt": "2026-11-12T10:00:05.000Z",
  "workspaceId": "acc_01jd2x7d3f5h7k9m1p3r5t7v9x",
  "data": {}
}
```

- **One event per occurrence**, delivered to every active endpoint of the workspace that listens for its type.
- **`connection.needs_reauth`** is sent only when the status changes, never again while it stays so. Reconnecting the account sends `connection.connected` with `reconnected: true`.
- **`connection.disconnected`** is sent after the account's monitors are deleted, so `deletedMonitorIds` lists them (empty when there were none).
- **`connection.invite_expired`** comes from a check that runs every minute, so it arrives within about a minute of `expiresAt`. A customer who is in the middle of connecting when the invite expires gets to finish (their sign-in has 10 minutes); the event then waits for that.
- **Duplicates.** An event's `id` is the same on every retry and redelivery: ignore an `id` you have already handled.
- `customId` is your own reference, the same as on the connection and the invite, so you can match the event to your customer's record.

## The attempt log

Every delivery keeps a log of its attempts, for monitor and endpoint deliveries alike:

`GET https://api.primaryapi.com/v1/monitors/{id}/deliveries/{deliveryId}`

Auth: API key with run, view or full access, or a dashboard session

`GET https://api.primaryapi.com/v1/webhook-endpoints/{id}/deliveries/{deliveryId}`

Auth: API key with full access, or a dashboard session (owners and admins)

Both answer the delivery with `attemptLog`, one entry per attempt, oldest first. The endpoint route also has `event`.

| Field | Type | Description |
|---|---|---|
| `attempt` | integer | `1` for the first attempt, up to `11`. |
| `startedAt` | string | When the attempt started. |
| `durationMs` | integer or null | Until your endpoint answered, or we gave up (timeout). `null` when the request never left: a blocked URL, a host that doesn't resolve, an event no longer kept. |
| `responseStatus` | integer or null | Your endpoint's HTTP status, or `null` when there was no response. |
| `error` | string or null | Why the attempt failed (below); `null` on a `2xx`. |
| `responseSnippet` | string or null | The first 1,024 bytes of your endpoint's response body, as text. `null` when the body was empty or not text. |
| `nextAttemptAt` | string or null | When the next attempt is due after this one; `null` after the last or a successful one. |

| `error` | What happened |
|---|---|
| `http_<status>` | Your endpoint answered with a status that isn't `2xx`, for example `http_503`. A `3xx` counts too (`http_301`): redirects are not followed. |
| `timeout` | No answer within 10 seconds. |
| `connection_refused` | Your server refused the connection: nothing is listening on that host and port. |
| `connection_reset` | Your server closed the connection before answering. |
| `tls_failed` | The secure connection failed: an expired, self-signed or wrong-host certificate, or no TLS version in common. |
| `connect_failed` | Any other failure to connect, for example a host that can't be reached. |
| `dns_failed` | The URL's host doesn't resolve. Not sent. |
| `blocked_url` | The URL points to a private, local or reserved address. Not sent. |
| `invalid_url` | The URL is not valid. Not sent. |
| `response_too_large` | Your endpoint answered with a body over 1 MB. |
| `event_unavailable` | The event's body was no longer kept, so nothing was sent. |
| `internal_error` | We could not sign or build the request. Not sent; it is retried. |

```json title="GET /v1/webhook-endpoints/{id}/deliveries/{deliveryId} (excerpt)"
{
  "id": "whd_01jd3m2b9e1g3j5m7p9r1t3v5x",
  "eventType": "connection.connected",
  "status": "succeeded",
  "attempts": 3,
  "attemptLog": [
    {
      "attempt": 1,
      "startedAt": "2026-11-12T10:14:03.530Z",
      "durationMs": 212,
      "responseStatus": 503,
      "error": "http_503",
      "responseSnippet": "{\"error\":\"maintenance\"}",
      "nextAttemptAt": "2026-11-12T10:14:08.742Z"
    },
    {
      "attempt": 2,
      "startedAt": "2026-11-12T10:14:08.742Z",
      "durationMs": 10004,
      "responseStatus": null,
      "error": "timeout",
      "responseSnippet": null,
      "nextAttemptAt": "2026-11-12T10:14:48.746Z"
    },
    {
      "attempt": 3,
      "startedAt": "2026-11-12T10:14:48.746Z",
      "durationMs": 87,
      "responseStatus": 200,
      "error": null,
      "responseSnippet": "ok",
      "nextAttemptAt": null
    }
  ],
  "event": { "id": "evt_01jd3m2a7c9e1g3j5m7p9r1t3v", "type": "connection.connected", "…": "…" }
}
```

The log is kept as long as its delivery ([How long events are kept](#how-long-events-are-kept)). The delivery lists keep their shape: `lastResponseStatus` and `lastError` (a short line) describe the last attempt only.

## Answer with a 2xx, quickly

Any `2xx` status within 10 seconds counts as delivered; anything else, a timeout or a refused connection is a failed attempt, which is retried. Answer first and do the work afterwards, for example by putting the event on a queue. Keep the response body short and free of secrets: we keep its first 1,024 bytes in the attempt log, where everyone who can see your deliveries can read it.

- Redirects are not followed: a `3xx` is a failed attempt. Point the monitor or endpoint at the final URL.
- The URL must be `https://` and public. Private, local and internal addresses are refused when you save the URL, and again on every attempt, so an address that later resolves to a private network is never contacted.
- Events can arrive in a different order than they happened (a retry can land after a newer event). Order by `createdAt` (or `run.createdAt`) if it matters, and ignore an `id` you have already handled.

## Verify the signature

Monitor and endpoint events are signed the same way, with the same secret and the same headers. The `PrimaryAPI-Signature` header is `t=<timestamp>,v1=<signature>`: `<timestamp>` is when this attempt was signed, in Unix seconds, and `<signature>` is the hex HMAC-SHA256 of `<timestamp>.<raw body>`, keyed with your signing secret (the whole `whsec_…` string). To check a request:

Read the **raw** body, exactly the bytes you received. Parsing the JSON and serialising it again changes the bytes, and the signature no longer matches.

Split the header on `,` and each part on the first `=`: take `t`, and every `v1` (there is one today; accept a match with any of them).

Compute HMAC-SHA256 of `t + "." + rawBody` with the secret, as hex, and compare it with `v1` in constant time.

Refuse a `t` more than 5 minutes away from your clock: that stops someone from replaying an old request they captured.

```ts tab="Node.js"
import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.PRIMARYAPI_WEBHOOK_SECRET!; // whsec_…
const TOLERANCE_SECONDS = 300;

export function verifyPrimaryApiSignature(rawBody: string, header: string | undefined): boolean {
  if (!header) return false;
  let timestamp = '';
  const signatures: string[] = [];
  for (const part of header.split(',')) {
    const i = part.indexOf('=');
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === 't') timestamp = value;
    if (key === 'v1') signatures.push(value);
  }
  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac('sha256', SECRET).update(`${timestamp}.${rawBody}`).digest();
  return signatures.some((s) => {
    const got = Buffer.from(s, 'hex');
    return got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}

const app = express();

// express.raw keeps the exact bytes: never verify a body that went through express.json().
app.post('/hooks/primaryapi', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verifyPrimaryApiSignature(rawBody, req.get('PrimaryAPI-Signature'))) {
    return res.status(400).send('invalid signature');
  }
  const event = JSON.parse(rawBody);
  res.sendStatus(200); // answer first…
  handleEvent(event); // …then work. Skip an event.id you have already handled.
});
```

```python tab="Python"
import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["PRIMARYAPI_WEBHOOK_SECRET"].encode()  # whsec_…
TOLERANCE_SECONDS = 300

def verify_primaryapi_signature(raw_body: bytes, header: str | None) -> bool:
    if not header:
        return False
    timestamp, signatures = "", []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

app = Flask(__name__)

@app.post("/hooks/primaryapi")
def primaryapi_webhook():
    raw_body = request.get_data()  # the exact bytes we sent
    if not verify_primaryapi_signature(raw_body, request.headers.get("PrimaryAPI-Signature")):
        abort(400)
    event = request.get_json()
    enqueue(event)  # do the work after answering; skip an event["id"] you have already handled
    return "", 200
```

Each attempt is signed afresh, so a retry carries a new `t` and `v1` for the same body.

## Retries

A failed attempt is retried after these waits, each counted from the attempt before:

| Attempt | Waits after the previous one | Total since the first |
|---|---|---|
| 1 | — | right after the run or the change |
| 2 | 5 seconds | 5 s |
| 3 | 30 seconds | 35 s |
| 4 | 2 minutes | 2 min 35 s |
| 5 | 5 minutes | 7 min 35 s |
| 6 | 15 minutes | 22 min 35 s |
| 7 | 1 hour | 1 h 23 min |
| 8 | 4 hours | 5 h 23 min |
| 9 | 12 hours | 17 h 23 min |
| 10 | 24 hours | 1 day 17 h |
| 11 | 48 hours | 3 days 17 h |

After the 11th failed attempt the delivery is marked `failed` and nothing more is sent for it. Every attempt carries the same `PrimaryAPI-Event-Id`. Retries continue while you fix your endpoint, so a short outage on your side loses nothing. The deliveries lists (`GET /v1/monitors/{id}/deliveries`, `GET /v1/webhook-endpoints/{id}/deliveries`, and the monitor's page or **Settings › Webhooks** in the dashboard) show each delivery's status, its attempts, the next attempt's time and the last response; the [attempt log](#the-attempt-log) shows every attempt.

A monitor's webhook that is still undelivered after every retry counts as a failed run ([When runs keep failing](/docs/monitors#when-runs-keep-failing)). Deleting a monitor or an endpoint gives up the deliveries still waiting for a retry.

## Redeliver

`POST https://api.primaryapi.com/v1/monitors/{id}/deliveries/{deliveryId}/redeliver`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

`POST https://api.primaryapi.com/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/redeliver`

Auth: API key with full access, or a dashboard session (owners and admins)

Sends the same event again as a new delivery: the same body and `PrimaryAPI-Event-Id`, a new `PrimaryAPI-Delivery-Id`, attempts counted from 1, to the monitor's or endpoint's **current** URL. Use it after fixing an endpoint, or to replay an event you lost. **201 Created**: the new delivery after its first attempt.

Redelivery needs the event's body, which is kept only as long as your plan says (below). Once it is gone the answer is `422 unprocessable` with `details.reason: "event_body_deleted"`. An endpoint delivery's `event` is `null` by then.

## How long events are kept

An event's body is kept by the workspace's plan, fixed when the event is made: a later plan change doesn't shorten or extend what was already decided.

| Plan | Event bodies are kept | Redelivery |
|---|---|---|
| Pay as you go | Until its delivery is done (delivered, or retries used up) | Only while a delivery of the event is still pending or retrying |
| Builder | 7 days | Within 7 days |
| Pro | 30 days | Within 30 days |
| Scale | 90 days | Within 90 days |
| Enterprise | 90 days, or as agreed | Within that time |

- Events of a monitor that reads a [connected account](/docs/monitors#what-is-kept) are the exception on every plan: they hold private data, so each one is stored encrypted only until it is delivered or its retries end, then deleted. Run the monitor again to send a fresh result.
- Deliveries and their attempt logs are listed for 30 days, or as long as the event's body is kept when that is longer. The delivery's status, attempts and times stay listed after the body is gone.
- A body is never deleted while a delivery of it is still pending or retrying.

## Test events

`POST https://api.primaryapi.com/v1/monitors/{id}/test`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Sends a `monitor.test` event, signed like any other, to check your endpoint and your signature check. It is free and runs nothing. **201 Created**: the delivery after its first attempt. Endpoints have their own: `POST /v1/webhook-endpoints/{id}/test` sends `webhook_endpoint.test` ([Webhook endpoints](#webhook-endpoints)).

## The signing secret

Every workspace has one signing secret for all its webhooks: every monitor and every endpoint. Owners and admins see it in the dashboard (**Settings › Webhooks**); with the API it takes a key with full access:

`GET https://api.primaryapi.com/v1/webhooks/secret`

Auth: API key with full access, or a dashboard session (owners and admins)

**200 OK**: `{ "secret": "whsec_…", "createdAt": "…" }`, made on first use.

`POST https://api.primaryapi.com/v1/webhooks/secret/rotate`

Auth: API key with full access, or a dashboard session (owners and admins)

Replaces the secret. **200 OK**: the new `{ secret, createdAt }`. The new secret is in force at once: every later attempt, retries included, is signed with it. Deploy it to your endpoint right away; attempts your endpoint refuses in the meantime are retried on the schedule above. Treat the secret like a password: keep it out of source control and logs, and rotate it if it may have leaked.
