Developers
Using the API

Webhooks

Register a target URL so NoCFO can POST events instead of you polling.

Webhook subscriptions are per business. {business_slug} comes from list businesses.

Webhook subscriptions - List is GET /v1/business/{business_slug}/webhook_subscriptions/. It is paginated.

Webhook subscription - Create is the POST on that path. The schema requires:

FieldMeaning
nameA name for this subscription.
target_urlWhere NoCFO sends the webhook.
basic_auth_usernameUsername your endpoint expects on the delivery request.

basic_auth_password and is_active are on the schema. Read the reference page before you omit them. Send Idempotency-Key on the POST so a retry does not create two subscriptions. See Idempotency.

Retrieve, replace, update, and delete are separate operations under /webhook_subscriptions/{subscription_id}/. subscription_id comes from the list or the create response.

Your endpoint should authenticate the delivery with the basic-auth username you registered. Do not treat an unsigned call to target_url as a NoCFO event if the credentials do not match.

Delivery

For each event in the business, NoCFO sends one POST to the target_url of every active subscription. What the body contains and which events exist is on Webhook events.

RuleValue
MethodPOST
HeadersContent-Type: application/json and Authorization: Basic <base64(username:password)>
Targethttps:// only. The host must resolve to a public IP address.
Timeout10 seconds
RedirectsNot followed. A 3xx counts as a failure.
SuccessAny 2xx status

A failed attempt is retried after 30 seconds, 2 minutes, 5 minutes, 15 minutes, and 30 minutes. That is six attempts in about 52 minutes. After the last failure NoCFO stops trying that event. It is not sent again later, so read the list endpoints to catch up after an outage.

A failure is a non-2xx status, a timeout, or a connection error. A 4xx is retried like a 5xx.

Setting is_active to false stops new deliveries, and pending retries for that subscription stop as well. Events that happen while a subscription is inactive are not queued for later.

On this page