Update a webhook subscription

Parameters

• idpath · stringrequired
• Idempotency-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_reuse rather 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 503 idempotency_unavailable with Retry-After, and nothing runs or is charged: retry with the same key.

Request body application/json, required

• urlstring (uri)

  New destination URL. It must use HTTPS, or http:// to localhost or 127.0.0.1 outside production — the hosted API is production, so it accepts HTTPS only.

• eventsstring[]

  On this portal a subscription names order.created, order.paid, order.in_production, order.shipped, order.delivered, order.cancelled, order.failed, order.updated, order.quality_check, order.issue, order.approval_requested, order.approval_approved, order.approval_declined, order.approval_expired, product.updated, catalog.synced, webhook.disabled, *; any other event is refused with 400 event_not_available. An event this subscription already names is kept, whatever its family.

  at least 1 entry

• activeboolean

  false pauses delivery: events already queued for this endpoint are held, not sent, and go out where their retry schedule left off once it is true again. Events raised while it is paused are not queued for it; replay them with POST /v1/events/{eventId}/replay after resuming.

• modestring

  Which traffic this endpoint receives. "test" delivers only sandbox events, "live" only real ones, "all" (the default) both. Account-level events — catalog syncs, delivery-failure notices, design proofs — arrive on every subscription regardless. Every mode-bearing event carries test_mode in its payload, stamped from the same decision that routed it.

  One of all test live

  Default all

Request

curl -X PATCH "https://portal.printedsimply.com/api/v1/webhooks/whk_SV8d5wGm2kUnSwx_RhZfY9OE" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-webhook-$(date +%s)" \
  -d '{
    "events": [
      "order.shipped",
      "order.delivered",
      "order.cancelled"
    ]
  }'

Response 200

{
  "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": null,
    "previous_secret_expires_at": null,
    "rotation_pending": false,
    "inbox": false
  },
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}

Errors

• 400validation_errorevent_not_available

  Invalid request body or parameters. When the request failed the operation's schema, details carries formErrors (problems with the request as a whole), fieldErrors (messages keyed by top-level field) and errors: one { pointer, code, message } per refused value, pointer an RFC 6901 JSON pointer into the body (or into the object of query parameters, for a query parameter) — /items/0/sku, with ~ written ~0 and / written ~1, and "" for the request as a whole. POST /v1/orders/bulk answers errors as one { index, details } per refused order, each details with its own pointers from the request body (/orders/3/items/0/sku); POST /v1/orders/multi-ship keeps errors as the { formErrors, fieldErrors } it always published; POST /v1/mockups/generate and POST /v1/products/recommend keep their fields at the top of details, with errors beside them. A refusal of a rule the schema cannot state (an asset that does not exist, an expiry too soon) names it in message and carries no errors. event_not_available — events names an event this portal does not offer (another family's, or one it never raises: order.rerouted); refused before anything is saved. details.events names each one and details.available lists the events a subscription can name here.

• 401invalid_api_keymissing_api_keykey_expired

  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).

• 403live_key_required

  live_key_required — a test key cannot move a subscription to live or all traffic. A test key changes only test-mode subscriptions; any other answers 404.

• 404

  Resource not found

• 413payload_too_large

  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.

• 429rate_limit_exceededdaily_quota_exceeded

  Rate limit exceeded. Two windows can produce this status and error.code says which: rate_limit_exceeded for the per-minute sliding window, daily_quota_exceeded for the plan's daily quota. Both carry Retry-After; the daily one also carries X-Daily-Limit and X-Daily-Remaining. The per-minute limits are plan-based — see Rate Limits above, or call GET /v1/me for this credential's own figures.