Webhooks
A webhook is an HTTP request, triggered by an event in a source system and sent to a destination system, usually with a payload of data. Webhooks are automated, in other words they are automatically sent out when their event is fired in the source system.
You can use webhook notifications to listen for events on your CabCard account so your integration can automatically trigger actions.
A webhook endpoint defines:
- a complete endpoint URL, for example https://api.your-company.com/webhooks/cabcard
- the event types you wish to receive webhook notifications for
- which account the webhook notifications will be sent for
Each webhook endpoint also has its own signature secret which you can use to verify incoming webhook notifications.
CabCard currently supports webhook notifications for the following events:
- sale.created
- intent.authorized
Webhooks can be attached at the submerchant (driver) level, or the operator (fleet) level. You can set up a new webhook endpoint in the Developer Tools section of your online dashboard (either my.cabcard.services or fleets.cabcard.services).
Please note that your URL must be prefixed by https. We are unable to set up localhost addresses for testing purposes. We recommend using a tool like Ngrok during development.
We recommend you verify incoming webhook notifications, especially if you intend to take actions based on these webhooks which might have a financial impact, for example crediting a driver's account. This is to help prevent abuse and fraud.
After your webhook endpoint has been set up, we will provide you with a signing secret. This should be stored safely within your application (for example, in environment variables), and should not be exposed publicly.
All webhooks will be sent with a signature header Webhook-Signature. The header value will include a timestamp tsp and a SHA256 hash digest sig in the following format:
To verify a webhook:
- Extract the timestamp and signatures from the header. Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix tsp corresponds to the timestamp, and sig corresponds to the signature (or signatures). You can discard any other elements.
- Prepare the signed payload string. This is accomplished by conactenating: the timestamp (as a string), the character ., the actual JSON payload (i.e. the request body) as a string.
- Determine the expected signature. Compute an HMAC with the SHA256 hash function. Use your endpoint’s signing secret as the key, and use the signed payload string from step 2 as the message.
- Compare the signature in the header to the expected signature. If they don't match, don't proceed.
A code sample for verifying webhook signatures is shown below:
For each event occurrence, CabCard will send a POST request containint the webhook data to your endpoint URL in JSON format. The full event details are included and can be used directly after parsing the JSON. Therefore, your webhook endpoint needs to expect data through a POST request and confirm successful receipt of that data.
To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code to the originating server. All response codes outside this range, including 3xx codes, indicate to that you did not receive the event.
If a 2xx HTTP status code is not received, the notification attempt will be repeated, with retries attempted in an exponential backoff fashion. After multiple failures to send the notification, the event will be marked as failed and further sends will not be attempted. After multiple days without receiving any 2xx HTTP status code responses, the endpoint will be considered as misconfigured and automatically disabled. You will need to fix the problem and re-enable the endpoint.
Because properly acknowledging receipt of the webhook notification is so important, your endpoint should return a 2xx HTTP status code prior to any complex logic that could cause a timeout.
You can use the developer tools section of your CabCard dashboard to view all notification attempts for a given endpoint.
It is advisable to make the webhook request operation on youre integration idempotent, as you may receive the same webhook notification more than once. In this scenario, you would want to ensure that your response to a webhook request is not duplicated.
In addition, we cannot guarantee that event webhook notifications will be delivered within a particular time window (although our system attempts to deliver notifications as soon as possible). Therefore we recommend that your integration should not be time-sensitive.
All events share a common format, with specific event types containing certain properties.
The webhook request body will contain the following properties:
- id String - a unique identifier for the object
- type String - the event type, for example sale.created, submerchant.updated, payout.updated
- createdAt String - date and time of the event creation, in ISO 8601 format, for example 2020-10-11T22:44:30.652Z
- data Object - data associated with this event.
Detailed information about the data field for the most commonly used events are found below.
The data property will contain the following properties:
- sale Object - sale transaction associated with this event
- submerchant Object - submerchant associated with this event (if sale is allocated to a submerchant)
- balanceTransaction Object - balance transaction associated with this event
Depending on the method used to accept this payment (POS, E-commerce or SoftPOS) the following additional properties may be included:
- terminal Object - terminal associated with this event if sale was carried out using a POS terminal (sale property method has value pos).
- intent Object - payment intent associated with this event if sale arose from a completed payment intent (sale property method has value ecommerce).
Example: webhook notification payload for ecommerce (payment link) transaction:
Example: webhook notification payload for POS (terminal) transaction:
This event is triggered when a payment intent in capture mode: manual is authorized. An example webhook payload is available on request.