Webhooks

Webhooks POST event data to your application. Subscription management uses the API-key flow under https://my.bluesuite.app/api/webhooks, separate from REST v1.

POST /api/webhooks/subscribe

Requires webhooks:write. Send JSON with trigger_event and an absolute webhook_url. Optional fields are zapier_subscription_id (string) and filters (an object of exact-match data-field filters).

curl 'https://my.bluesuite.app/api/webhooks/subscribe' \
  -H "Authorization: Bearer $BLUESUITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"trigger_event":"new_request","webhook_url":"https://example.com/hooks/bluesuite"}'

Returns 200 with success: true and a subscription object containing its numeric ID, event, URL, active state, creation date, and optional Zapier subscription ID.

Supported subscription events:

Event	Meaning
`new_request`	Request created
`request_updated`	Request updated
`new_contact`	Contact created
`contact_updated`	Contact updated
`new_quote`	Quote created
`quote_accepted`	Quote accepted
`new_job`	Job created
`new_invoice`	Invoice created
`invoice_sent`	Invoice moved to sent
`invoice_paid`	Invoice moved to paid

An invoice status event is not proof of customer delivery or a card charge. See Invoices and Payments.

List subscriptions

GET /api/webhooks/list

Requires webhooks:read. Optionally filter by trigger_event. Returns { "success": true, "subscriptions": [...], "count": 1 }, including active state, timestamps, URL, filters, and integration ID. It does not return signing secrets.

Unsubscribe

DELETE /api/webhooks/unsubscribe

Requires webhooks:write. Send { "subscription_id": 123 } in the JSON body. Returns success and a confirmation message.

Send a test

POST /api/webhooks/test

Requires both webhooks:read and webhooks:write. Send subscription_id and trigger_event. The test endpoint accepts the subscription events above except request_updated. This sends an HTTP request to the subscribed URL.

The response includes success, status_code, response_body, error, and message. Inspect success; the management request can return HTTP 200 even if the test delivery failed.

Payload

{
  "event": "new_request",
  "workspace_id": 123,
  "timestamp": "2026-10-27T14:00:00.000Z",
  "data": {"id": 456},
  "meta": {
    "webhook_id": "123",
    "delivery_attempt": 1,
    "link": "https://my.bluesuite.app/requests/456"
  }
}

data contains the event-specific record. meta.webhook_id is the subscription ID, not a unique event/delivery ID, so do not deduplicate every message on that value alone. Resource links are generated by the server; consume the supplied URL.

Signatures

The current wire headers retain the former product name for compatibility:

X-BluePro-Signature: sha256=<hex digest>
X-BluePro-Event
X-BluePro-Workspace-ID

The signature is HMAC-SHA256 over the serialized JSON body using the subscription secret. If you have provisioned that secret, verify against the original request body bytes with a constant-time comparison. The public subscribe/list responses currently omit the secret, so they alone do not provide a self-service signing-secret setup. Do not expect an X-BlueSuite-Signature header.

Delivery and retries

Return a 2xx response promptly; outbound delivery times out after 30 seconds. Failed deliveries are retried on a best-effort, in-process schedule (one minute, five minutes, fifteen minutes, then one hour, up to five attempts total). Retries are not a durable queue and can be lost when the process stops. Reconcile critical state through the REST API and make your receiver tolerant of duplicate events.

Management errors can use { "error": "...", "details": [...] } without the REST v1 success envelope. Missing/invalid credentials return 401, invalid data returns 400, and unexpected failures return 500. Legacy-format keys additionally require a workspace_id query parameter.