DocsWebhook Event Schemas
Payload formats for Cost+ webhook notifications
Cost+ sends webhook notifications to your configured webhook_url when order or transaction statuses change. This page documents the event payload formats.
For webhook configuration, retry logic, and best practices, see the Webhooks guide.
OrderStatusChangedEvent
Sent when an order's status changes (e.g., from new to completed).
{
"event": "status_changed",
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"order_id": "b9ae6d70-1234-5678-9abc-def012345678"
}| Field | Type | Description |
|---|---|---|
event | string | Always "status_changed" |
project_id | string (UUID) | The project this order belongs to |
order_id | string (UUID) | The order whose status changed |
The webhook payload only contains the order ID — not the new status. Always verify the current status by calling Get Order before taking action (e.g., shipping goods or granting access).
TransactionStatusChangedEvent
Sent when an individual transaction's status changes within an order.
{
"event": "transaction_status_changed",
"merchant_id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"order_id": "b9ae6d70-1234-5678-9abc-def012345678",
"transaction_id": "c8d7e6f5-4321-0987-6543-210fedcba098",
"transaction_status": "completed"
}| Field | Type | Description |
|---|---|---|
event | string | Always "transaction_status_changed" |
merchant_id | string (UUID) | Your merchant identifier |
project_id | string (UUID) | The project this order belongs to |
order_id | string (UUID) | The parent order |
transaction_id | string (UUID) | The specific transaction whose status changed |
transaction_status | string | New status: new, pending, processing, accepted, captured, completed, cancelled, error, or expired |
Delivery & Retries
- Cost+ retries up to 10 times, spaced 2 minutes apart
- First attempt times out after 4 seconds; subsequent retries after 10 seconds
- Your endpoint must return a 2xx status code to acknowledge receipt
- If all 10 retries fail, the event is marked as failed
Webhook URL Configuration
You can set the webhook URL in two ways:
- Per order — include
webhook_urlin the Create Order request - Project-level — configure a default webhook URL in the Merchant Portal under your website settings