API Reference

Webhooks

Subscribe to workspace events and receive HTTPS POST deliveries when matching records change. Each subscription covers one event type per workspace.

Last updated 2026-06-10

Webhooks let your integration react to changes in a workspace without polling. Create a subscription for a specific event (for example `customer.created`), provide a public HTTPS callback URL, and COUNT delivers a JSON payload whenever that event occurs.

Only subscriptions with status `active` receive deliveries. You may optionally configure a signing secret; COUNT then sends an `X-Webhook-Signature` header on every delivery so you can verify authenticity.

Key concepts

One subscription per event

Each workspace allows one subscription per event type per partner. Creating a duplicate returns an error — update the existing subscription instead.

Delivery payload

Deliveries are HTTPS POST requests with a JSON body containing `id`, `event`, `apiVersion`, `occurredAt`, `team`, and `data`. Verify the raw request bytes against your signing secret.

Signature verification

When a signing secret is configured, COUNT sends `X-Webhook-Signature: sha256=<hex>` where the hex is HMAC-SHA256 of the raw body using your secret. See the Verify Webhook Deliveries guide for a walkthrough.

Callback URL requirements

Callback URLs must be public HTTPS endpoints. Localhost and private IP addresses are rejected when creating or updating a subscription.

The webhook subscription object

Fields returned when you list, create, or update a subscription.

Attributes

uuiduuid

Subscription identifier. Use this value in update and delete paths.

eventenum

The event type this subscription listens for.

One of: customer.created, customer.updated, customer.deleted, vendor.created, vendor.updated, vendor.deleted, transaction.created, transaction.updated, transaction.deleted, invoice.created, invoice.updated, invoice.deleted, bill.created, bill.updated, bill.deleted

callbackUrlstring

Public HTTPS URL that receives POST deliveries.

statusenum

Only active subscriptions receive deliveries.

One of: active, paused, disabled

createdAtdatetime

ISO 8601 timestamp when the subscription was created.

updatedAtdatetime

ISO 8601 timestamp of the last update.

Example

{
  "uuid": "e0f1a2b3-c4d5-6789-ef01-234567890abc",
  "event": "customer.created",
  "callbackUrl": "https://webhook.site/your-unique-id",
  "status": "active",
  "createdAt": "2026-03-01T09:00:00.000Z",
  "updatedAt": "2026-03-01T09:00:00.000Z"
}

Signing secret is write-only

The signing secret is never returned in list or retrieve responses. Store it securely when you create or update a subscription. Pass `signingSecret: null` on update to clear it.

Test with a request catcher

Use a service like webhook.site to capture deliveries while developing. Point your subscription callback URL there, trigger the event, and inspect the payload and signature header.