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.
Last updated
On this page
PrimaryAPI sends webhooks from two places:
- Monitors. A monitor sends its results to its own webhook URL.
- Webhook endpoints. URLs your workspace registers to hear about its 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
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 |
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. 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). Every other event leaves it out, so treat a missing field as "not paused".
{
"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.
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:
{
"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
eventsout 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 unprocessablewithdetails.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
fullaccess. Every other role and key gets403 forbidden, reads included.
api.primaryapi.com/ v1/ webhook-endpointsAuth: 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.
api.primaryapi.com/ v1/ webhook-endpointsAuth: 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.
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.
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.
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 }.
api.primaryapi.com/ v1/ webhook-endpoints/ {id}/ testAuth: 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.
api.primaryapi.com/ v1/ webhook-endpoints/ {id}/ deliveriesAuth: 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.
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) and event: the body as sent, while it is kept (How long events are kept), then null.
api.primaryapi.com/ v1/ webhook-endpoints/ {id}/ deliveries/ {deliveryId}/ redeliverAuth: 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). 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.
{
"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
}
}{
"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.
{
"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"
}
}
}{
"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"]
}
}{
"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"
}
}
}{
"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_reauthis sent only when the status changes, never again while it stays so. Reconnecting the account sendsconnection.connectedwithreconnected: true.connection.disconnectedis sent after the account's monitors are deleted, sodeletedMonitorIdslists them (empty when there were none).connection.invite_expiredcomes from a check that runs every minute, so it arrives within about a minute ofexpiresAt. 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
idis the same on every retry and redelivery: ignore anidyou have already handled. customIdis 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:
api.primaryapi.com/ v1/ monitors/ {id}/ deliveries/ {deliveryId}Auth: API key with run, view or full access, or a dashboard session
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. |
{
"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). 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
3xxis 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(orrun.createdAt) if it matters, and ignore anidyou 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.
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.
});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 "", 200Each 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 shows every attempt.
A monitor's webhook that is still undelivered after every retry counts as a failed run (When runs keep failing). Deleting a monitor or an endpoint gives up the deliveries still waiting for a retry.
Redeliver
api.primaryapi.com/ v1/ monitors/ {id}/ deliveries/ {deliveryId}/ redeliverAuth: API key with run or full access, or a dashboard session (owners, admins, developers)
api.primaryapi.com/ v1/ webhook-endpoints/ {id}/ deliveries/ {deliveryId}/ redeliverAuth: 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 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
api.primaryapi.com/ v1/ monitors/ {id}/ testAuth: 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).
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:
api.primaryapi.com/ v1/ webhooks/ secretAuth: API key with full access, or a dashboard session (owners and admins)
200 OK: { "secret": "whsec_…", "createdAt": "…" }, made on first use.
api.primaryapi.com/ v1/ webhooks/ secret/ rotateAuth: 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.