Issues a new signing secret and keeps the outgoing one valid for grace_hours (default 24, max 168). Deliveries in the window are signed with both, so you can deploy the new secret with no dropped events. The new secret is returned once, here.
- Credential
- An API key in
x-api-key - Scopes
webhooks:manage
Parameters
idpath · stringrequiredIdempotency-Keyheader · string (uuid)Unique key for idempotent requests. If you retry a request with the same key within 24 hours, you receive the original response. The key is bound to the request payload: reusing it for a different payload returns 422
idempotency_key_reuserather than the original response, so a changed request is never silently dropped. The binding is over the JSON's content, not its bytes — keys in another order or other whitespace are the same request. Generate a new key for each new request. On an operation that moves money (an order, a batch, an item, a shipping or address change, a cancellation's refund), a key that cannot be checked because the idempotency ledger is unreachable is answered 503idempotency_unavailablewithRetry-After, and nothing runs or is charged: retry with the same key.
Request body application/json
grace_hoursintegerHow long the outgoing secret keeps verifying. 0 cuts over immediately.
Default 24 · 0 to 168
Request
POST /api/v1/webhooks/{id}/rotate-secret
curl -X POST "https://portal.printedsimply.com/api/v1/webhooks/whk_SV8d5wGm2kUnSwx_RhZfY9OE/rotate-secret" \
-H "x-api-key: ps_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: rotate-webhook-secret-$(date +%s)" \
-d '{
"grace_hours": 24
}'Response 200
The new secret in the clear — the second and last time you see it — with grace_hours and previous_secret_expires_at bounding the window in which BOTH secrets verify. Accept either until then.
data
idstringrequiredurlstringrequiredeventsstring[]requiredactivebooleanrequiredmodestringrequiredWhich order mode this subscription accepts. Normalised on the way out, so a stored value this build does not know reads as what it is actually routed as (
all) rather than as the stored string.One of
alltestlivecreated_atstring (date-time)requiredsecret_rotated_atstring (date-time) | nullprevious_secret_expires_atstring (date-time) | nullDuring a rotation both secrets verify until this moment. Sign-check against both, or accept the older one, until it passes.
rotation_pendingbooleanTrue while the previous secret is still inside its window.
inboxbooleanrequiredTrue for the account's hosted test inbox (POST /v1/webhooks/inbox): it receives test events only and keeps them for GET /v1/webhooks/inbox rather than POSTing them, its
urlis the dashboard page that shows them, and its url and mode cannot be changed.secretstringrequiredThe NEW secret, in the clear. As on create, this is the last time you will see it.
grace_hoursintegerrequiredHow long the outgoing secret keeps verifying, measured from
secret_rotated_atand restated here so a receiver knows its window without arithmetic. Both secrets verify untilprevious_secret_expires_at; accept either until then. Zero means cut over now, with no overlap written at all.
meta
pageintegertotalintegerlimitintegerThe page size actually applied, which is not necessarily the one asked for — the operation's own ceiling wins.
pagesintegertotaloverlimit, rounded up.next_cursorstring | nullOn a cursor-paged operation: send this back as
cursorfor the next page. Null on the last page. Absent on operations that do not page by cursor.has_morebooleanOn a list operation whose
metaisListMeta: whether another page follows this one.
{
"status": "success",
"data": {
"id": "whk_hCyrY24j_gUrQWxJ7ji6s9st",
"url": "https://example.com/hooks/orders",
"events": [
"order.shipped",
"order.delivered",
"order.cancelled"
],
"active": true,
"mode": "test",
"created_at": "2026-10-15T15:00:26.000Z",
"secret_rotated_at": "2026-10-15T15:00:36.000Z",
"previous_secret_expires_at": "2026-10-16T15:00:36.000Z",
"rotation_pending": true,
"inbox": false,
"secret": "df33a8999390b44d0827dc3897e680cce9f376136ee934601cb44cc44f0cead0",
"grace_hours": 24
},
"request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}Errors
Invalid request body or parameters. When the request failed the operation's schema,
detailscarriesformErrors(problems with the request as a whole),fieldErrors(messages keyed by top-level field) anderrors: one{ pointer, code, message }per refused value,pointeran RFC 6901 JSON pointer into the body (or into the object of query parameters, for a query parameter) —/items/0/sku, with~written~0and/written~1, and""for the request as a whole. POST /v1/orders/bulk answerserrorsas one{ index, details }per refused order, eachdetailswith its own pointers from the request body (/orders/3/items/0/sku); POST /v1/orders/multi-ship keepserrorsas the{ formErrors, fieldErrors }it always published; POST /v1/mockups/generate and POST /v1/products/recommend keep their fields at the top ofdetails, witherrorsbeside them. A refusal of a rule the schema cannot state (an asset that does not exist, an expiry too soon) names it inmessageand carries noerrors.Missing, invalid or expired API key:
missing_api_key(none sent),invalid_api_key(unknown or revoked),key_expired(past the expiry set when it was created; create a new key).404Resource not found
payload_too_large — the request body exceeded this route's byte cap (256 KB unless the route raises it with a written reason). It is refused before it is parsed, so nothing was created. Send fewer rows, or use the endpoint's own asynchronous door where it has one.
Rate limit exceeded. Two windows can produce this status and
error.codesays which:rate_limit_exceededfor the per-minute sliding window,daily_quota_exceededfor the plan's daily quota. Both carryRetry-After; the daily one also carriesX-Daily-LimitandX-Daily-Remaining. The per-minute limits are plan-based — see Rate Limits above, or call GET /v1/me for this credential's own figures.