This document provides a guide for integrating with Litecard’s webhook API. Litecard’s Webhooks allow you to receive various real-time events such as card creation or card download. In this guide, you will learn how to register a webhook endpoint to receive information back from Litecard. As a result, you will receive event data and can write it to your CDP or data warehouse.
Introduction
Our webhook API is designed to be straightforward and efficient, providing you with immediate notifications of significant events. By configuring a webhook endpoint, you can have our system push data to your application as events happen, rather than requiring you to poll our API regularly.
- Concepts
Webhook Endpoint
This is a URL on your server that our system will send HTTP POST requests to when an event occurs. Your server should be configured to listen for these requests and process the incoming data.
Events
These are specific actions or changes within our system that trigger a webhook notification. Each event type has a predefined data structure that will be included in the POST request body.
Payload
The data sent to your webhook endpoint in the body of the HTTP POST request. This payload will be in JSON format and will contain information about the event that occurred.
Authentication
When registering your webhook, you can either select NONE or API_KEY. None will mean no authentication is expected to communicate with your registered endpoint.
API_KEY means Litecard will use an API key with a designated header to call your registered endpoint.
Payload Structure
Sample Payload
{
“event”: “string”,
“timestamp”: “string”,
“deviceType”: “string”,
“status”: “string”,
“data”: {}
}
Payload Schema
The JSON payload for each event will generally follow this structure:
| Field | Type | Description | enum |
|---|---|---|---|
| event | String | The name of the event | CARD_CREATE CARD_UPDATE CARD_DOWNLOAD CARD_REMOVE REGISTER_WEBHOOK |
| timestamp | String | Date timestamp of the event | |
| deviceType | String | If event CARD_DOWNLOAD or CARD_REMOVE , deviceType is included to indicate the user’s device | APPLE GOOGLE |
| status | String | The general status of the Card | CREATE ACTIVE INACTIVE |
| data | String | For events CARD_CREATE and CARD_UPDATE. There is no set schema as it depends on the template used to generate the Card. For the CARD_UPDATE event, it will only include data fields that were updated during this event. | |
| templateId | String | For event CARD_CREATE, the ID of the the template used to generate the Card | |
| templateName | String | For event CARD_CREATE, the Name of the template used to generate the Card | |
| cardId | String | For all events, the ID of the card related to the event |
- Available Events
| Event Type | Description | Data Fields |
|---|---|---|
| CARD_CREATE | Triggered when a card gets created via Litecard’s system | event timestamp status data |
| CARD_UPDATE | Triggered when a card gets updated in Litecard’s system | event timestamp status data |
| CARD_DOWNLOAD | Triggered when a user downloads a Litecard Card into their device | event timestamp status deviceType |
| CARD_REMOVE | Triggered when a user removes a Litecard Card from their device | event timestamp status deviceType |
| REGISTER_WEBHOOK | Register Webhook event, used to verify webhook connection | event |
- Registering your webhook
Endpoint Details
| Field | Description |
|---|---|
| Endpoint URL | /api/v1/webhook/external |
| Method | POST |
| Description | Register a client webhook for supported events |
| Authentication | Bearer Token – see Litecard API guide for more details |
Request JSON Payload Schema
The POST request to /api/v1/webhook/external can contain the following keys in the request payload
| Field | Type | Required | Description |
|---|---|---|---|
| webhookUrl | String | Yes | The endpoint for Litecard to send the download data |
| method | String | Yes | HTTP Method etc POST |
| authType | String | Yes | The type of Auth to use for the webhook. Currently only supports API_KEY |
| authConfig | authConfig | Yes | Auth configuration |
| events | String[] | Yes | List of events this Webhook should be subscribed to |
| provider | String | No | Currently not in use. |
authConfig Object Schema #
Configuration details for the webhook
| Field | Type | Required | Description |
|---|---|---|---|
| securityHeader | String | Yes | Security Header that Litecard will include in calls to the webhook. |
| apiKey | String | Yes | API Key used to authenticate to the webhook. This will be stored securely. |
- Responding to Webhooks
Your webhook endpoint should respond with an HTTP 200 OK status code within a reasonable timeframe (e.g., within 5 seconds) to acknowledge receipt of the webhook. Any other status code (e.g., 4xx or 5xx) will indicate a failure, and our system may retry sending the webhook.
- Retry logic
Litecard will attempt to call the endpoint again when it does not receive a Status 200. Litecard utilises AWS’ SQS service to manage events and will attempt to retry up to 5 times with gradual delays between attempts until the event is resolved or the limit is reached.
Thank you. For any further questions, please contact dev@litecard.com
