Kapitale sends real-time notifications via webhook when order events occur. With the webhook configured, the partner receives updates automatically.How to request configuration#
The partner must contact the Kapitale team via email (suporte@kapitale.com.br) to request webhook configuration. Indicate that you want to configure the webhook to receive order notifications and provide the configuration data listed in the following section.Configuration fields#
When requesting configuration, the partner must provide the following fields:| Field | Required | Type | Description | Restrictions |
|---|
endpoint_url | Yes | string | HTTPS URL that will receive notifications | Valid URL, max. 2048 characters |
auth_token | No | string | Token for request authentication | Max. 512 characters. If provided, auth_type is required |
auth_type | No | enum | Authentication type | basic or bearer. Required if auth_token is provided |
custom_headers | No | object | Additional HTTP headers | Up to 20 key-value pairs (string) |
Example of data to provide:{
"endpoint_url": "https://mysystem.com/webhook/kapitale",
"auth_type": "bearer",
"auth_token": "your-secret-token",
"custom_headers": {
"X-Custom-Header": "value"
}
}
Content-Type: application/json
Authentication: As configured (Basic or Bearer in the Authorization header)
Custom headers: As per configured custom_headers
Payload structure#
The request body follows the base structure for all events:{
"event_type": "event.name",
"destination_id": "industry-uuid",
"data": { ... }
}
event_type: Event type identifier
destination_id: Industry UUID (useful for partners with multiple integrations)
data: Object with event-specific data
Events and payloads#
order.created#
Triggered when a new order is created.| Field | Type | Description |
|---|
order_id | uuid | Internal order ID |
order_no | string | Order number (e.g., ORD-2024-001) |
status | string | Payment status (e.g., pending) |
created_at | string | Creation date (ISO 8601) |
cnpj | string | Retail CNPJ (source company) |
{
"event_type": "order.created",
"destination_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"order_id": "660e8400-e29b-41d4-a716-446655440001",
"order_no": "ORD-2024-001",
"status": "pending",
"created_at": "2024-01-15T10:30:00.000Z",
"cnpj": "12345678000190"
}
}
order.approved#
Triggered when the order payment is approved.| Field | Type | Description |
|---|
order_id | uuid | Internal order ID |
order_no | string | Order number |
status | string | Payment status (e.g., approved) |
cnpj | string | Retail CNPJ |
decided_at | string | Approval decision date (ISO 8601) |
{
"event_type": "order.approved",
"destination_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"order_id": "660e8400-e29b-41d4-a716-446655440001",
"order_no": "ORD-2024-001",
"status": "approved",
"cnpj": "12345678000190",
"decided_at": "2024-01-16T14:20:00.000Z"
}
}
order.reproved#
Triggered when the order payment is rejected.| Field | Type | Description |
|---|
order_id | uuid | Internal order ID |
order_no | string | Order number |
status | string | Payment status (e.g., denied) |
cnpj | string | Retail CNPJ |
decided_at | string | Rejection decision date (ISO 8601) |
denial_reason | string | Rejection reason |
{
"event_type": "order.reproved",
"destination_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"order_id": "660e8400-e29b-41d4-a716-446655440001",
"order_no": "ORD-2024-001",
"status": "denied",
"cnpj": "12345678000190",
"decided_at": "2024-01-16T14:25:00.000Z",
"denial_reason": "Incomplete documentation"
}
}
status values, refer to the Status Map.Best practices#
Fast response: The endpoint should respond with 2xx status quickly. If processing is time-consuming, process asynchronously and return success immediately.
Idempotency: Implement idempotency in your endpoint, as events may be resent in case of delivery failure.
HTTPS: The endpoint must use HTTPS to ensure data security.
Modified at 2026-03-13 16:44:56
