Webhooks
PaidGet an HTTP callback when a Carbon record is created, changed, or deleted.
A webhook sends an HTTP POST to a configured URL when a record in a subscribed table is inserted, updated, or deleted. Use webhooks to react to changes without polling the API.
Subscribable tables
Each webhook subscribes to one table. The following tables support subscriptions:
| Module | Tables |
|---|---|
| Sales | customer, quote, salesOrder, salesRfq |
| Purchasing | purchaseOrder, supplier, supplierQuote |
| Invoicing | salesInvoice, purchaseInvoice |
| Production | job |
| Inventory | receipt |
| Items | item |
| Users | employee |
Select at least one trigger operation: insert, update, or delete.
The payload
Carbon sends a JSON body to the configured URL. type identifies the operation, record contains the affected row, and old contains the previous row for updates.
{
"type": "UPDATE",
"table": "salesOrder",
"companyId": "abc123",
"eventId": "1042",
"record": { "id": "...", "salesOrderId": "SO000042", "status": "To Ship and Invoice" },
"old": { "id": "...", "salesOrderId": "SO000042", "status": "Draft" }
}old appears only for updates. For deletes, record contains the last state of the deleted row. Carbon sets Content-Type: application/json, then applies any headers in the delivery configuration.
eventId identifies one change. It remains stable across delivery retries and differs for each new change, including repeated updates to the same record. Use it as the idempotency key.
Configuration
Create and manage webhooks under Settings → Webhooks. A webhook has:
- Name: a label, unique within your company.
- Table: the one table to watch.
- URL: where the
POSTis sent; must be a valid URL. - Triggers: any of insert, update, delete (at least one).
- Active: webhooks are on by default; switch off to pause delivery.
Carbon tracks success and error counts and the latest timestamp for each outcome.
Delivery & reliability
Webhook delivery is asynchronous and normally occurs a few seconds after the database change.
Delivery is at least once. If the endpoint does not return a success status within 30 seconds, Carbon retries with exponential backoff before marking the change as failed. Design for these conditions:
- Handle duplicates. A request can be retried after your service has processed it. De-duplicate on
eventId, nottypeandrecord.id, because separate changes to the same record share the latter values. - Reconcile after outages. After retries are exhausted, Carbon drops the change and increments the error count. Query the API when complete event processing is required.
The success and error counters record one outcome per change, not per attempt, so a retried-then-delivered event counts once as a success.
Carbon does not sign webhook payloads and sends no shared-secret or signature header. Use HTTPS and include an unguessable token in the URL path or query. Reject requests without the token.