Events and payload
Webhook requests carry X-Octane-Event, X-Octane-Delivery and X-Octane-Signature headers and a JSON envelope with the full transaction object.
Each webhook is an HTTPS POST with three X-Octane-* headers and a JSON envelope whose data.transaction is exactly the object the Pull API returns. The envelope id is the delivery id, stable across retries.
The request
POST /your/webhook/path HTTP/1.1
Host: erp.example.com
Content-Type: application/json
User-Agent: Octane-Webhooks/1.0
X-Octane-Event: transaction.confirmed
X-Octane-Delivery: 5f0c2e7a-0d3f-5c1a-9b8e-2a4c6d8e0f13
X-Octane-Signature: t=1758358803,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd| Header | Description |
|---|---|
X-Octane-Event | The event type. Same value as type in the body. |
X-Octane-Delivery | The delivery id. Same value as id in the body. Use it to de-duplicate. |
X-Octane-Signature | Timestamp and HMAC-SHA256 signature of the body. See Signature verification. |
User-Agent | Always Octane-Webhooks/1.0. |
The envelope
{
"id": "5f0c2e7a-0d3f-5c1a-9b8e-2a4c6d8e0f13",
"type": "transaction.confirmed",
"created_at": "2026-09-20T09:00:03Z",
"api_version": "2026-09-01",
"data": {
"transaction": { "...": "see below" }
}
}| Field | Description |
|---|---|
id | Delivery id. Deterministic for a given transaction and key: every retry or redelivery of the same event carries the same id. Store it and ignore duplicates. |
type | transaction.confirmed, transaction.external or webhook.test. |
created_at | When the event was created, ISO 8601 UTC. |
api_version | Version of the payload schema. Currently 2026-09-01. |
data.transaction | The transaction object. Identical to the Pull API transaction object. |
Event types
transaction.confirmed
Sent when a transaction becomes CONFIRMED. data.transaction.status is CONFIRMED. Refund transactions are included and carry correction_reference_id.
{
"id": "5f0c2e7a-0d3f-5c1a-9b8e-2a4c6d8e0f13",
"type": "transaction.confirmed",
"created_at": "2026-09-20T09:00:03Z",
"api_version": "2026-09-01",
"data": {
"transaction": {
"id": 185432,
"status": "CONFIRMED",
"created_at": "2026-09-20T08:59:36.340Z",
"confirmed_at": "2026-09-20T09:00:02.110Z",
"correction_reference_id": null,
"corporate": { "id": 67, "name": "Acme Logistics" },
"corporate_group": { "id": 9, "name": "Acme Group" },
"fuel": {
"type": { "id": 2, "name": "Benzine 92" },
"liters": 18.5,
"price_per_liter": 13.75,
"amount": 254.38
},
"odometer_reading": 120450,
"distance_traveled": 312,
"fuel_consumption": 5.93,
"station": {
"id": 164,
"name": "Misr Petroleum - Ring Road",
"provider": { "id": 7, "name": "Misr Petroleum" },
"is_external": false
},
"vehicle": {
"id": 4,
"code": "V-004",
"number_plate": "ABC 1234",
"chassis_number": "JTDBR32E720123456",
"brand": "Toyota",
"model": "Hilux",
"year": 2021,
"department": { "id": 3, "name": "Distribution" }
},
"driver": { "id": 31, "name": "Ahmed Mostafa" },
"fees": {
"total_fees": 1.06,
"total_vat": 0.13,
"total_amount": 255.435000
},
"images": {
"pump": "https://storage.example/pump.jpg?X-Amz-Expires=86400&...",
"odometer": "https://storage.example/odometer.jpg?X-Amz-Expires=86400&...",
"expires_at": "2026-09-21T09:00:03Z"
}
}
}
}transaction.external
Sent when an EXTERNAL transaction is recorded. Same envelope and transaction shape; status is EXTERNAL, station.is_external is true, station.id and station.provider are null, and fees are sent exactly as recorded.
webhook.test
Sent on request by Octane so you can verify connectivity and your signature check. The envelope is the same and type is webhook.test. Verify the signature and return 2xx. Do not treat its data as a real transaction.
How does the payload differ from the Pull API?
| Topic | Pull API | Webhook |
|---|---|---|
| Image URL validity | 1 hour | 24 hours, re-signed on every delivery attempt |
| Ordering | Newest first, paginated | One event per delivery, in the order transactions are confirmed (not guaranteed) |
Driver mobile_number | Only when enabled on the key | Same |
Everything else, including field names, nullability and precision, is identical.