Session Webhook
The Session Webhook notifies your system whenever a payment session changes its state.
This enables your platform to react in real time — for example, when a session becomes active, fails or expires.
When it's triggered
Status | Description | Typical Use Case |
session_active | The session was successfully initialized and is currently active. | The session has started and the customer interracts with payment flow. |
cancelled | The customer cancelled the session manually or closed the checkout. | Stop tracking the session and mark it as cancelled. |
failed | The session failed due to a technical or validation error (e.g. payment method unavailable, invalid data). | Display a failure message or log the error for retry. |
session_expired | The session expired automatically after a timeout (1 hour) without completing checkout. | Mark session as expired and cancel related pending processes. |
order_created | Checkout was successfully completed and an order has been created. | Confirm the order and trigger fulfillment in your system. |
Example Payloads
Each webhook uses the same payload structure. Only the status field changes to indicate the current session state.
Payload Parameters:
- status — current session status
- invoiceNumber — internal invoice number
- transactionId — unique transaction identifier
- billinkInvoiceNumber — public invoice number, generated by Billink based on invoiceNumber
Example: session_active
{
"status": "session_active",
"invoiceNumber": "invoice-1234",
"transactionId": "tx_001a45",
"billinkInvoiceNumber": "1ABinvoice-1234"
}Example: cancelled
{
"status": "cancelled",
"invoiceNumber": "invoice-1234",
"transactionId": "tx_001a45",
"billinkInvoiceNumber": "1ABinvoice-1234"
}Example: failed
{
"status": "failed",
"invoiceNumber": "invoice-1234",
"transactionId": "tx_001a45",
"billinkInvoiceNumber": "1ABinvoice-1234"
}Example: session_expired
{
"status": "session_expired",
"invoiceNumber": "invoice-1234",
"transactionId": "tx_001a45",
"billinkInvoiceNumber": "1ABinvoice-1234"
}Example: order_created
{
"status": "order_created",
"invoiceNumber": "invoice-1234",
"transactionId": "tx_001a45",
"billinkInvoiceNumber": "1ABinvoice-1234"
}Delivery and Retries
When a webhook is triggered, Billink sends an HTTPS POST request to your configured webhook URL with the corresponding event payload.
If your endpoint does respond with HTTP 200-299, the system will automatically retry delivery up to three times:
Attempt | Delay before retry |
1st retry | after 5 seconds |
2nd retry | after 10 seconds |
3rd retry | after 15 seconds |
After three failed attempts, the webhook is considered undeliverable, and no further retries will be made.
To ensure successful delivery:
- Always respond with HTTP 200 OK as soon as your system receives the webhook.
- Handle processing asynchronously to avoid timeouts.
- Log all incoming webhook attempts for debugging and reconciliation.
What made this section unhelpful for you?
On this page
- Session Webhook