Webhooks overview
Octane sends a signed HTTPS POST to your endpoint when a transaction is confirmed or an external transaction is recorded. Endpoint requirements and event types.
Webhooks let Octane notify your system in near real time, instead of you polling the Pull API. Whenever one of your transactions is confirmed, or an external transaction is recorded, Octane sends an HTTPS POST to your endpoint with the full transaction record.
How do webhooks work?
- You give Octane an HTTPS URL when your API key is created (or later, on request). Octane generates a webhook secret and shares it with you once.
- When a transaction reaches
CONFIRMEDorEXTERNAL, Octane builds the payload andPOSTs it to your URL, signed with the secret. - Your endpoint verifies the signature and returns any
2xxstatus within 500 ms. - If delivery fails, Octane retries up to 3 times. Persistent failures are logged and, after prolonged failure, the webhook is disabled and you are notified by email.
A feed of new transactions, not a lifecycle mirror
Webhooks fire once per transaction, when it becomes CONFIRMED or EXTERNAL. Later changes (a void or cancellation) are not pushed. Use the Pull API to detect them. See Best practices.
Endpoint requirements
| Requirement | Detail |
|---|---|
| Scheme and port | https:// on port 443 only. Plain HTTP and non-standard ports are rejected. |
| Reachability | The hostname must resolve to a public IP address. Private, loopback, link-local and cloud-metadata ranges are rejected. |
| TLS | A valid, publicly trusted certificate. |
| Redirects | Not followed. The URL must respond directly. |
| Timeout | Respond within 500 ms, measured from connection to complete response. Return 2xx immediately, then process the event asynchronously. A slow response counts as a failed delivery. |
| Success | Any 2xx status. The response body is ignored. |
One webhook URL is configured per API key. If you need several destinations, ask Octane for a key per destination.
What triggers a webhook?
| Event | Sent when |
|---|---|
transaction.confirmed | A transaction becomes CONFIRMED, including refund transactions for duplicates, variances and resolved disputes. |
transaction.external | An EXTERNAL transaction (a station outside the Octane network) is recorded. |
webhook.test | On request, to verify your endpoint. |
Not sent: PENDING, VOID or CANCELED transactions, later status changes of a transaction already delivered, and manual balance adjustments.
Only transactions created after the webhook URL was set are pushed. Use the Pull API to backfill anything earlier.