Webhooks API

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

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

Example

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

Response

List webhook endpoints

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.

Example

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

Response

Create a webhook endpoint

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

Request body

Example

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

Response

Get a webhook endpoint

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

Parameters

Example

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

Response

Update a webhook endpoint

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.

Parameters

Request body

Example

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

Response

Delete a webhook endpoint

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

Parameters

Example

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

Response

Turn a webhook endpoint on or off

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.

Parameters

Request body

Example

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

Response

Regenerate the signing 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.

Parameters

Example

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

Response

List an endpoint's 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.

Parameters

Example

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

Response

Get a delivery

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

Parameters

Example

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

Response

Resend a delivery

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.

Parameters

Example

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

Response

Send a test event

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.

Parameters

Example

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

Response

List domain 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.

Parameters

Example

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

Response