Webhooks

Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.

List subscriptions and the event catalog

GET /webhooks

Scope: webhooks:manage. Operation id: listWebhooks.

Example request

curl "https://api.showpilot.com/v1/webhooks" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Subscriptions (secrets never shown) and every event type you can subscribe to.

Field	Type	Always	Meaning
`items`	array of Webhook	yes
`catalog`	array of string	yes

Webhook

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`url`	string (uri)	yes
`events`	array of string	yes	Event types, or `["*"]` for all.
`description`	string	yes
`status`	`active` · `paused`	yes
`consecutiveFailures`	integer	yes
`lastDeliveredAt`	string or null (date-time)	yes
`lastFailedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

POST /webhooks

Scope: webhooks:manage. Operation id: createWebhook.

The response carries the signing secret once. Verify every delivery: X-ShowPilot-Signature is sha256= HMAC-SHA256 over <X-ShowPilot-Timestamp>.<raw body> with the secret; reject anything older than five minutes. Deliveries retry with backoff over five attempts; twenty failures in a row pause the subscription.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.

Example request

curl "https://api.showpilot.com/v1/webhooks" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 201.

The subscription, with its secret.

Every field of Webhook, plus:

Field	Type	Always	Meaning
`secret`	string	yes	Shown only here.

Webhook

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`url`	string (uri)	yes
`events`	array of string	yes	Event types, or `["*"]` for all.
`description`	string	yes
`status`	`active` · `paused`	yes
`consecutiveFailures`	integer	yes
`lastDeliveredAt`	string or null (date-time)	yes
`lastFailedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

One subscription

GET /webhooks/{id}

Scope: webhooks:manage. Operation id: getWebhook.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/webhooks/a0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The subscription.

Webhook

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`url`	string (uri)	yes
`events`	array of string	yes	Event types, or `["*"]` for all.
`description`	string	yes
`status`	`active` · `paused`	yes
`consecutiveFailures`	integer	yes
`lastDeliveredAt`	string or null (date-time)	yes
`lastFailedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Change the url, events, description or status

PATCH /webhooks/{id}

Scope: webhooks:manage. Operation id: updateWebhook.

Setting status to active also resets the failure count after a pause.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/webhooks/a0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The updated subscription.

Webhook

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`url`	string (uri)	yes
`events`	array of string	yes	Event types, or `["*"]` for all.
`description`	string	yes
`status`	`active` · `paused`	yes
`consecutiveFailures`	integer	yes
`lastDeliveredAt`	string or null (date-time)	yes
`lastFailedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Remove a subscription

DELETE /webhooks/{id}

Scope: webhooks:manage. Operation id: deleteWebhook.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/webhooks/a0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 204. Removed.

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Delivery log for a subscription, newest first

GET /webhooks/{id}/deliveries

Scope: webhooks:manage. Operation id: listWebhookDeliveries.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)
`limit`	query	integer	Page size, 1 to 200. Default 50.
`cursor`	query	string	The `nextCursor` from the previous page. Opaque; never build one.

Example request

curl "https://api.showpilot.com/v1/webhooks/a0000001-0000-4000-8000-000000000000/deliveries?limit=50" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

One page of deliveries.

Field	Type	Always	Meaning
`items`	array of WebhookDelivery	yes
`nextCursor`	NextCursor	yes

WebhookDelivery

Field	Type	Always
`id`	string (uuid)	yes
`eventId`	string	yes
`status`	`pending` · `delivered` · `failed`	yes
`attempts`	integer	yes
`responseStatus`	integer or null	yes
`error`	string or null	yes
`deliveredAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes

NextCursor

Pass as cursor for the next page; null on the last page.

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Send an event again

POST /webhooks/{id}/deliveries/{deliveryId}/replay

Scope: webhooks:manage. Operation id: replayWebhookDelivery.

Queues a fresh delivery of the same event to the same endpoint.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)
`deliveryId`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/webhooks/a0000001-0000-4000-8000-000000000000/deliveries/b0000001-0000-4000-8000-000000000000/replay" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 202.

The new delivery, queued.

WebhookDelivery

Field	Type	Always
`id`	string (uuid)	yes
`eventId`	string	yes
`status`	`pending` · `delivered` · `failed`	yes
`attempts`	integer	yes
`responseStatus`	integer or null	yes
`error`	string or null	yes
`deliveredAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page