DevelopersAPI reference

Webhooks API

REST endpoints for webhooks in SKUFlow: 13 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

OperationEndpointRisk
List event typesGET /organizations/{organizationId}/webhooks/event-typesread
List webhook endpointsGET /organizations/{organizationId}/webhooksread
Create a webhook endpointPOST /organizations/{organizationId}/webhookssensitive
Get a webhook endpointGET /organizations/{organizationId}/webhooks/{webhookId}read
Update a webhook endpointPATCH /organizations/{organizationId}/webhooks/{webhookId}sensitive
Delete a webhook endpointDELETE /organizations/{organizationId}/webhooks/{webhookId}sensitive
Turn a webhook endpoint on or offPOST /organizations/{organizationId}/webhooks/{webhookId}/activewrite
Regenerate the signing secretPOST /organizations/{organizationId}/webhooks/{webhookId}/secretsensitive
List an endpoint's deliveriesGET /organizations/{organizationId}/webhooks/{webhookId}/deliveriesread
Get a deliveryGET /organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}read
Resend a deliveryPOST /organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}/resendsensitive
Send a test eventPOST /organizations/{organizationId}/webhooks/{webhookId}/testwrite
List domain eventsGET /organizations/{organizationId}/eventsread

List event types

GET /organizations/{organizationId}/webhooks/event-types

The event catalogue: every domain event type with its area (for subscribing by area), what it means, its payload version and the fields of its data (ids and safe fields only). Read-only.

Permissionintegrations.manage (Owner, Admin)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP toolwebhooks_eventTypes (toolset settings)

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/event-types" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
areasarray of enum
eventsarray of object
events[].typestring
events[].areaenumOne of customers, sales, invoices, payments, team, inventory, engagement, marketing, website, stores, orders, reviews, phone, system.
events[].descriptionstring
events[].versioninteger
events[].fieldsarray of string

List webhook endpoints

GET /organizations/{organizationId}/webhooks

The organization's webhook endpoints with their subscribed events, whether they are on, the secret's last four characters, the last delivery and how many deliveries are failing. Read-only.

Permissionintegrations.manage (Owner, Admin)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP toolwebhooks_list (toolset settings)

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

An array of objects:

FieldTypeDescription
idstring
urlstring
descriptionstring or null
eventTypesarray of stringEmpty = every event.
activeboolean
secretHintstringThe signing secret's last four characters.
consecutiveDeadCountinteger
disabledAtstring or null
disabledReasonstring or nullWhy it was turned off automatically (repeated failures); null when turned off by hand.
createdByIdstring or null
createdAtstring
updatedAtstring
lastDeliveryAtstring or null
failingDeliveriesinteger

Create a webhook endpoint

POST /organizations/{organizationId}/webhooks

Sends data out: from now on, the organization's events (all, or eventTypes) are POSTed to url as JSON {id, type, occurredAt, organizationId, data}, signed with SKUFlow-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">. Returns the signing secret ONCE. Retries 1 m, 5 m, 30 m, 2 h, 12 h, then DEAD; an endpoint whose deliveries die 5 times in a row is turned off. Send a test with POST /webhooks/{webhookId}/test.

Permissionintegrations.manage (Owner, Admin)
Risksensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolwebhooks_create (toolset settings)
ApprovalWaits for your approval in SKUFlow when called with an API key or a connected app: the first call answers 428 APPROVAL_REQUIRED; once you approve it, repeat the call with the X-SKUFlow-Approval header. See Approvals.

Request body

FieldTypeRequiredDescription
urlstringYesWhere events are POSTed. https only (http://localhost only where the server allows private targets, i.e. development). Private, loopback and link-local addresses are refused. Up to 2048 characters.
descriptionstring or nullNoUp to 500 characters.
eventTypesarray of stringNoThe events to send; empty or omitted = every event. Up to 100 items.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Response

201: the answer's fields
FieldTypeDescription
endpointobject
endpoint.idstring
endpoint.urlstring
endpoint.descriptionstring or null
endpoint.eventTypesarray of stringEmpty = every event.
endpoint.activeboolean
endpoint.secretHintstringThe signing secret's last four characters.
endpoint.consecutiveDeadCountinteger
endpoint.disabledAtstring or null
endpoint.disabledReasonstring or nullWhy it was turned off automatically (repeated failures); null when turned off by hand.
endpoint.createdByIdstring or null
endpoint.createdAtstring
endpoint.updatedAtstring
endpoint.lastDeliveryAtstring or null
endpoint.failingDeliveriesinteger
secretstringThe signing secret (whsec_…). Shown this once: store it now; reads only show its last four characters.

Get a webhook endpoint

GET /organizations/{organizationId}/webhooks/{webhookId}

One endpoint with its delivery counts by status. The secret is never returned here (only its last four characters). Read-only.

Permissionintegrations.manage (Owner, Admin)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP toolwebhooks_get (toolset settings)

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
urlstring
descriptionstring or null
eventTypesarray of stringEmpty = every event.
activeboolean
secretHintstringThe signing secret's last four characters.
consecutiveDeadCountinteger
disabledAtstring or null
disabledReasonstring or nullWhy it was turned off automatically (repeated failures); null when turned off by hand.
createdByIdstring or null
createdAtstring
updatedAtstring
lastDeliveryAtstring or null
failingDeliveriesinteger
deliveryCountsobject
deliveryCounts.PENDINGinteger
deliveryCounts.SUCCEEDEDinteger
deliveryCounts.FAILEDinteger
deliveryCounts.DEADinteger

Update a webhook endpoint

PATCH /organizations/{organizationId}/webhooks/{webhookId}

Sends data out: change an endpoint's URL, description or subscribed events (empty = all). A new URL receives every later event. The secret is unchanged.

Permissionintegrations.manage (Owner, Admin)
Risksensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolwebhooks_update (toolset settings)
ApprovalWaits for your approval in SKUFlow when called with an API key or a connected app: the first call answers 428 APPROVAL_REQUIRED; once you approve it, repeat the call with the X-SKUFlow-Approval header. See Approvals.

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.

Request body

FieldTypeRequiredDescription
urlstringNoWhere events are POSTed. https only (http://localhost only where the server allows private targets, i.e. development). Private, loopback and link-local addresses are refused. Up to 2048 characters.
descriptionstring or nullNoUp to 500 characters.
eventTypesarray of stringNoThe events to send; empty or omitted = every event. Up to 100 items.

Example

curl -X PATCH "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","description":"string","eventTypes":["string"]}'

Response

200: the answer's fields
FieldTypeDescription
idstring
urlstring
descriptionstring or null
eventTypesarray of stringEmpty = every event.
activeboolean
secretHintstringThe signing secret's last four characters.
consecutiveDeadCountinteger
disabledAtstring or null
disabledReasonstring or nullWhy it was turned off automatically (repeated failures); null when turned off by hand.
createdByIdstring or null
createdAtstring
updatedAtstring
lastDeliveryAtstring or null
failingDeliveriesinteger

Delete a webhook endpoint

DELETE /organizations/{organizationId}/webhooks/{webhookId}

Destructive: deletes the endpoint and its delivery log. Events stay in the event log. Turn it off instead to keep the log.

Permissionintegrations.manage (Owner, Admin)
Risksensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolwebhooks_delete (toolset settings)
ApprovalOver MCP, this tool always waits for your approval in SKUFlow. See Approvals.

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.

Example

curl -X DELETE "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
oktrue

Turn a webhook endpoint on or off

POST /organizations/{organizationId}/webhooks/{webhookId}/active

active: false pauses deliveries (they wait); active: true resumes them and clears an automatic turn-off and its failure count. Resend dead deliveries afterwards if needed.

Permissionintegrations.manage (Owner, Admin)
Riskwrite, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it.
MCP toolwebhooks_setActive (toolset settings)

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.

Request body

FieldTypeRequiredDescription
activebooleanYes

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}/active" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":true}'

Response

200: the answer's fields
FieldTypeDescription
idstring
urlstring
descriptionstring or null
eventTypesarray of stringEmpty = every event.
activeboolean
secretHintstringThe signing secret's last four characters.
consecutiveDeadCountinteger
disabledAtstring or null
disabledReasonstring or nullWhy it was turned off automatically (repeated failures); null when turned off by hand.
createdByIdstring or null
createdAtstring
updatedAtstring
lastDeliveryAtstring or null
failingDeliveriesinteger

Regenerate the signing secret

POST /organizations/{organizationId}/webhooks/{webhookId}/secret

Replaces the endpoint's signing secret and returns the new one ONCE. The old secret stops working at once: update the receiver first or accept failed verifications until then.

Permissionintegrations.manage (Owner, Admin)
Risksensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolwebhooks_regenerateSecret (toolset settings)
ApprovalWaits for your approval in SKUFlow when called with an API key or a connected app: the first call answers 428 APPROVAL_REQUIRED; once you approve it, repeat the call with the X-SKUFlow-Approval header. See Approvals.

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}/secret" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
endpointobject
endpoint.idstring
endpoint.urlstring
endpoint.descriptionstring or null
endpoint.eventTypesarray of stringEmpty = every event.
endpoint.activeboolean
endpoint.secretHintstringThe signing secret's last four characters.
endpoint.consecutiveDeadCountinteger
endpoint.disabledAtstring or null
endpoint.disabledReasonstring or nullWhy it was turned off automatically (repeated failures); null when turned off by hand.
endpoint.createdByIdstring or null
endpoint.createdAtstring
endpoint.updatedAtstring
endpoint.lastDeliveryAtstring or null
endpoint.failingDeliveriesinteger
secretstringThe signing secret (whsec_…). Shown this once: store it now; reads only show its last four characters.

List an endpoint's deliveries

GET /organizations/{organizationId}/webhooks/{webhookId}/deliveries

The delivery log, newest first: event type, status (PENDING, SUCCEEDED, FAILED = will retry, DEAD = out of attempts), attempts, the last HTTP status, time taken and error, the next attempt. Filter with status. Read-only.

Permissionintegrations.manage (Owner, Admin)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP toolwebhooks_deliveries (toolset settings)

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.
statusqueryenumNoOne of PENDING, SUCCEEDED, FAILED, DEAD.
limitqueryintegerNoPage size, 1–200. Default 50.
offsetqueryintegerNoRows to skip; the answer's total counts every match. Default 0.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}/deliveries" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
itemsarray of object
items[].idstring
items[].endpointIdstring
items[].eventIdstring
items[].eventTypestring
items[].eventOccurredAtstring
items[].subjectTypestring
items[].subjectIdstring
items[].statusenumOne of PENDING, SUCCEEDED, FAILED, DEAD.
items[].attemptCountinteger
items[].nextAttemptAtstring or null
items[].lastAttemptAtstring or null
items[].completedAtstring or null
items[].responseStatusinteger or null
items[].latencyMsinteger or null
items[].errorstring or null
items[].createdAtstring
totalinteger

Get a delivery

GET /organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}

One delivery with the request body sent, the receiver's response (first 2 KB) and the last 10 attempts. Read-only.

Permissionintegrations.manage (Owner, Admin)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP toolwebhooks_getDelivery (toolset settings)

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.
deliveryIdpathstringYes

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}/deliveries/{deliveryId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
endpointIdstring
eventIdstring
eventTypestring
eventOccurredAtstring
subjectTypestring
subjectIdstring
statusenumOne of PENDING, SUCCEEDED, FAILED, DEAD.
attemptCountinteger
nextAttemptAtstring or null
lastAttemptAtstring or null
completedAtstring or null
responseStatusinteger or null
latencyMsinteger or null
errorstring or null
createdAtstring
requestBodystring or nullThe JSON envelope last sent.
responseBodystring or nullThe receiver's answer, first 2 KB.
attemptsarray of object
attempts[].atstring
attempts[].statusinteger or null
attempts[].latencyMsinteger or null
attempts[].errorstring or null

Resend a delivery

POST /organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}/resend

Sends data out: delivers the event to the endpoint again now, whatever its status, with a fresh signature; a failure starts a new retry schedule. 409 while a worker is sending it.

Permissionintegrations.manage (Owner, Admin)
Risksensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolwebhooks_resend (toolset settings)
ApprovalOver MCP, this tool always waits for your approval in SKUFlow. See Approvals.

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.
deliveryIdpathstringYes

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}/deliveries/{deliveryId}/resend" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
endpointIdstring
eventIdstring
eventTypestring
eventOccurredAtstring
subjectTypestring
subjectIdstring
statusenumOne of PENDING, SUCCEEDED, FAILED, DEAD.
attemptCountinteger
nextAttemptAtstring or null
lastAttemptAtstring or null
completedAtstring or null
responseStatusinteger or null
latencyMsinteger or null
errorstring or null
createdAtstring
requestBodystring or nullThe JSON envelope last sent.
responseBodystring or nullThe receiver's answer, first 2 KB.
attemptsarray of object
attempts[].atstring
attempts[].statusinteger or null
attempts[].latencyMsinteger or null
attempts[].errorstring or null

Send a test event

POST /organizations/{organizationId}/webhooks/{webhookId}/test

Records a webhook.test event for this endpoint only and delivers it now (signed like any event; no customer data). Answers the delivery with the receiver's response, so a setup can be checked in one call.

Permissionintegrations.manage (Owner, Admin)
Riskwrite, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it.
MCP toolwebhooks_sendTest (toolset settings)

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYesFrom GET /webhooks.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/webhooks/{webhookId}/test" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
endpointIdstring
eventIdstring
eventTypestring
eventOccurredAtstring
subjectTypestring
subjectIdstring
statusenumOne of PENDING, SUCCEEDED, FAILED, DEAD.
attemptCountinteger
nextAttemptAtstring or null
lastAttemptAtstring or null
completedAtstring or null
responseStatusinteger or null
latencyMsinteger or null
errorstring or null
createdAtstring
requestBodystring or nullThe JSON envelope last sent.
responseBodystring or nullThe receiver's answer, first 2 KB.
attemptsarray of object
attempts[].atstring
attempts[].statusinteger or null
attempts[].latencyMsinteger or null
attempts[].errorstring or null

List domain events

GET /organizations/{organizationId}/events

The outbox: every domain event the organization produced, newest first, with its payload (ids and safe fields), who caused it (USER, AGENT, SYSTEM, PUBLIC) and its webhook deliveries. Filter by type (exact, or a prefix ending in . such as invoice.), subjectType + subjectId (one record's history), actorUserId and from / to (UTC days). Useful to see what happened to a record. Read-only.

Permissionintegrations.manage (Owner, Admin)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP toolevents_list (toolset reports)

Parameters

NameInTypeRequiredDescription
typequerystringNoUp to 100 characters.
subjectTypequerystringNoinvoice, quote, customer, payment… Up to 50 characters.
subjectIdquerystringNo
actorUserIdquerystringNo
fromquerystringNoA calendar date in the business's own calendar, YYYY-MM-DD.
toquerystringNoA calendar date in the business's own calendar, YYYY-MM-DD.
limitqueryintegerNoPage size, 1–200. Default 50.
offsetqueryintegerNoRows to skip; the answer's total counts every match. Default 0.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/events" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
itemsarray of object
items[].idstring
items[].typestring
items[].versioninteger
items[].occurredAtstring
items[].subjectTypestring
items[].subjectIdstring
items[].actorTypeenumOne of USER, AGENT, SYSTEM, PUBLIC.
items[].actorUserIdstring or null
items[].dispatchedAtstring or nullWhen it was fanned out to webhooks and integrations.
items[].dataobject
items[].deliveriesobject
items[].deliveries.totalinteger
items[].deliveries.succeededinteger
items[].deliveries.failinginteger
totalinteger

On this page