Webhooks endpoints

Webhook endpoints, their signing secrets and the delivery log.

Base URL https://app.processcart.com/api/v1. Every operation below is also in the OpenAPI document and the interactive reference.

GET /v1/webhooks

List webhooks. Scope webhooks:manage · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated ({ data, nextCursor, hasMore }). Operation id listWebhooks · open in the API reference.

Lists the workspace's webhook endpoints, newest first (no secrets). updatedSince turns the list into an incremental sync ordered by updatedAt ascending (inclusive). Keys restricted to folders cannot use the webhook operations (403 not_allowed_for_key); keys restricted to workflows manage only webhooks whose workflowIds is a non-empty subset of their allowlist, and see only deliveries about those workflows (plus test events).

Query parameters (an unknown parameter is a 422 validation_failed with errors[].code = "unknown_parameter")

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 405 method_not_allowed — Method not allowed
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "data": [
    {
      "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
      "url": "https://hooks.example.com/processcart",
      "description": "Everything",
      "events": [
        "*"
      ],
      "workflowIds": null,
      "filters": {},
      "enabled": true,
      "disabledReason": null,
      "disabledAt": null,
      "consecutiveFailures": 0,
      "lastDeliveryAt": null,
      "createdAt": "2026-10-11T05:28:25.162Z",
      "createdBy": null,
      "updatedAt": "2026-10-11T05:28:25.162Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

POST /v1/webhooks

Create a webhook. Scope webhooks:manage · accepts Idempotency-Key. Operation id createWebhook · open in the API reference.

Subscribes an https endpoint to events (* = everything but the opt-in types), optionally narrowed to some workflows and, for field.updated, to some field keys. The response carries the Standard Webhooks signing secret ONCE — store it; rotate to get a new one. The URL is checked against the SSRF policy (public https only). Keys restricted to folders cannot use the webhook operations (403 not_allowed_for_key); keys restricted to workflows manage only webhooks whose workflowIds is a non-empty subset of their allowlist, and see only deliveries about those workflows (plus test events).

Request headers

Request body — application/json, WebhookConfig

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 413 payload_too_large — Payload too large
• 415 unsupported_media_type — Unsupported media type
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example request

{
  "url": "https://hooks.example.com/processcart",
  "description": "Everything",
  "events": [
    "*"
  ]
}

Example response (201)

{
  "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
  "url": "https://hooks.example.com/processcart",
  "description": "Everything",
  "events": [
    "*"
  ],
  "workflowIds": null,
  "filters": {},
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": null,
  "createdAt": "2026-10-11T05:28:25.162Z",
  "createdBy": null,
  "updatedAt": "2026-10-11T05:28:25.162Z",
  "secret": "whsec_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"
}

GET /v1/webhooks/{id}

Get a webhook. Scope webhooks:manage. Operation id getWebhook · open in the API reference.

Returns one webhook endpoint with its subscription, filters, enabled state, failure counter and last delivery time — never the secret.

Path parameters

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
  "url": "https://hooks.example.com/processcart",
  "description": "Everything",
  "events": [
    "*"
  ],
  "workflowIds": null,
  "filters": {},
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": null,
  "createdAt": "2026-10-11T05:28:25.162Z",
  "createdBy": null,
  "updatedAt": "2026-10-11T05:28:25.162Z"
}

PATCH /v1/webhooks/{id}

Update a webhook. Scope webhooks:manage · accepts Idempotency-Key. Operation id updateWebhook · open in the API reference.

Changes any subset of the configuration: url (re-checked against the SSRF policy), description, events, workflowIds (null clears the filter; omit the key to keep it) and filters. enabled is not part of the configuration — use the enable and disable operations. Audited.

Path parameters

Request headers

Request body — application/json, WebhookPatch

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 413 payload_too_large — Payload too large
• 415 unsupported_media_type — Unsupported media type
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example request

{
  "description": "Renamed",
  "events": [
    "run.created",
    "run.completed"
  ]
}

Example response (200)

{
  "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
  "url": "https://hooks.example.com/processcart",
  "description": "Renamed",
  "events": [
    "run.created",
    "run.completed"
  ],
  "workflowIds": null,
  "filters": {},
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2026-10-11T05:28:29.806Z",
  "createdAt": "2026-10-11T05:28:25.162Z",
  "createdBy": null,
  "updatedAt": "2026-10-11T05:28:30.342Z"
}

DELETE /v1/webhooks/{id}

Delete a webhook. Scope webhooks:manage · accepts Idempotency-Key. Operation id deleteWebhook · open in the API reference.

Removes the endpoint with its secret and delivery log. Pending deliveries are dropped; nothing is sent to the endpoint. Audited.

Path parameters

Request headers

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

POST /v1/webhooks/{id}/enable

Enable a webhook. Scope webhooks:manage · accepts Idempotency-Key. Operation id enableWebhook · open in the API reference.

Turns deliveries back on and resets the consecutive-failure counter — also the way to bring back an endpoint that was disabled automatically (after repeated failures or a 410). Enabling an enabled webhook answers 200 unchanged.

Path parameters

Request headers

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
  "url": "https://hooks.example.com/processcart",
  "description": "Everything",
  "events": [
    "*"
  ],
  "workflowIds": null,
  "filters": {},
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2026-10-11T05:28:27.885Z",
  "createdAt": "2026-10-11T05:28:25.162Z",
  "createdBy": null,
  "updatedAt": "2026-10-11T05:28:28.995Z"
}

POST /v1/webhooks/{id}/disable

Disable a webhook. Scope webhooks:manage · accepts Idempotency-Key. Operation id disableWebhook · open in the API reference.

Stops deliveries (reason manual). Events that happen while it is disabled are not queued for it. Disabling a disabled webhook answers 200 unchanged.

Path parameters

Request headers

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
  "url": "https://hooks.example.com/processcart",
  "description": "Everything",
  "events": [
    "*"
  ],
  "workflowIds": null,
  "filters": {},
  "enabled": false,
  "disabledReason": "manual",
  "disabledAt": "2026-10-11T05:28:28.437Z",
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2026-10-11T05:28:27.885Z",
  "createdAt": "2026-10-11T05:28:25.162Z",
  "createdBy": null,
  "updatedAt": "2026-10-11T05:28:28.437Z"
}

POST /v1/webhooks/{id}/rotate-secret

Rotate a webhook's signing secret. Scope webhooks:manage · accepts Idempotency-Key. Operation id rotateWebhookSecret · open in the API reference.

Mints a new signing secret and returns it once. Until previousExpiresAt every delivery is signed with both secrets (two entries in webhook-signature), so the endpoint can switch without missing a beat. Audited.

Path parameters

Request headers

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "secret": "whsec_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE",
  "previousExpiresAt": "2026-10-12T05:28:29.267Z"
}

POST /v1/webhooks/{id}/test

Send a test event. Scope webhooks:manage · accepts Idempotency-Key. Operation id testWebhook · open in the API reference.

Queues a webhook.test delivery to this endpoint and sends it right away (the response does not wait for the endpoint). Read the delivery to see the outcome. A disabled webhook is refused.

Path parameters

Request headers

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 idempotency_in_progress — Request in progress
• 409 webhook_disabled — Webhook disabled
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (202)

{
  "delivery": {
    "id": "eb2383ee-da26-48db-aaa3-42e61dc67272",
    "webhookId": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
    "attempt": 0
  }
}

GET /v1/webhooks/{id}/deliveries

List a webhook's deliveries. Scope webhooks:manage · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated ({ data, nextCursor, hasMore }). Operation id listWebhookDeliveries · open in the API reference.

The endpoint's delivery log, newest first, with each delivery's status, attempt count, last response code and next attempt time. Filter by status. Deliveries older than the retention window are gone. A key restricted to workflows sees only deliveries about those workflows (and test events).

Path parameters

Query parameters (an unknown parameter is a 422 validation_failed with errors[].code = "unknown_parameter")

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "data": [
    {
      "id": "eb2383ee-da26-48db-aaa3-42e61dc67272",
      "webhookId": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
      "eventId": "evt_9d68ebed-af3b-42da-aace-77503bb95cdc",
      "eventType": "webhook.test",
      "status": "delivered",
      "attemptCount": 1,
      "lastStatusCode": 200,
      "lastError": null,
      "lastAttemptAt": "2026-10-11T05:28:26.227Z",
      "nextAttemptAt": null,
      "deliveredAt": "2026-10-11T05:28:26.485Z",
      "createdAt": "2026-10-11T05:28:26.084Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

GET /v1/webhooks/{id}/deliveries/{deliveryId}

Get a delivery. Scope webhooks:manage. Operation id getWebhookDelivery · open in the API reference.

One delivery with the event envelope that was (or will be) POSTed — useful to inspect a failed delivery or to replay an event by hand.

Path parameters

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (200)

{
  "id": "eb2383ee-da26-48db-aaa3-42e61dc67272",
  "webhookId": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
  "eventId": "evt_9d68ebed-af3b-42da-aace-77503bb95cdc",
  "eventType": "webhook.test",
  "status": "delivered",
  "attemptCount": 1,
  "lastStatusCode": 200,
  "lastError": null,
  "lastAttemptAt": "2026-10-11T05:28:26.227Z",
  "nextAttemptAt": null,
  "deliveredAt": "2026-10-11T05:28:26.485Z",
  "createdAt": "2026-10-11T05:28:26.084Z",
  "payload": {
    "id": "evt_9d68ebed-af3b-42da-aace-77503bb95cdc",
    "org": {
      "id": "83b4ff3e-2634-423e-89ab-f2c5c07ced1f",
      "slug": "example-workspace"
    },
    "data": {
      "webhook": {
        "id": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa"
      }
    },
    "type": "webhook.test",
    "actor": {
      "kind": "api",
      "name": "Zapier",
      "keyId": "d5ec9555-1a0c-455a-86e6-c7b18bcabc78"
    },
    "timestamp": "2026-10-11T05:28:26.084Z"
  }
}

POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

Send a delivery again. Scope webhooks:manage · accepts Idempotency-Key. Operation id redeliverWebhookDelivery · open in the API reference.

Queues a finished delivery (delivered, failed or exhausted) again with the same webhook-id and sends it right away; the attempt count keeps counting. A delivery still in flight, or a disabled webhook, is refused. Audited.

Path parameters

Request headers

Responses

Errors (every code this operation can answer; see Errors)

• 401 invalid_api_key — Invalid API key
• 401 key_revoked — API key revoked
• 401 unauthorized — Authentication required
• 403 insufficient_scope — Insufficient scope
• 403 not_allowed_for_key — Not allowed for this key
• 403 read_only_key — Read-only key
• 404 not_found — Not found
• 405 method_not_allowed — Method not allowed
• 409 delivery_not_terminal — Delivery not finished
• 409 idempotency_in_progress — Request in progress
• 409 webhook_disabled — Webhook disabled
• 422 idempotency_key_reused — Idempotency key reused
• 422 validation_failed — Validation failed
• 429 rate_limited — Too many requests
• 500 internal_error — Internal error
• 503 unavailable — Service unavailable

Example response (202)

{
  "delivery": {
    "id": "eb2383ee-da26-48db-aaa3-42e61dc67272",
    "webhookId": "2b64ebdd-e0ba-4d01-aca7-914b36d905aa",
    "attempt": 1
  }
}