Listen to events in your Loopz gift card program on your webhook endpoint so your integration can automatically trigger reactions.
Why use webhooks
When building Loopz integrations, you might want your applications to receive events as they occur in your Loopz gift card program, so that your backend systems can execute actions accordingly.
To enable webhook events, you need to register webhook endpoints. After you register them, Loopz can push real-time event data to your application’s webhook endpoint when events happen in your Loopz gift card program. Loopz uses HTTPS to send webhook events to your app as a JSON payload that includes a Webhook Event object.
Receiving webhook events is particularly useful for listening to asynchronous events such as when a gift card is purchased, a gift card's balance changes, or when a specific transaction is recorded.
Webhook Event
The Webhook Event object we send to your webhook endpoint provides a snapshot of the object that changed. The request also contains several headers that provide context to the Webhook Event which you can use to correctly attribute the event to a specific merchant or gift card program.
The following webhook events are supported:
| Webhook Topic |
|---|
| gift-card.created |
| gift-card.updated |
| gift-card.deleted |
| transaction.created |
| transaction.updated |
| transaction.deleted |
| location.created |
| location.updated |
The JSON payload of the Webhook Event depends on the webhook topic. Gift card, Transaction and Location objects can be the payload of a Webhook Event.
Headers are present in the Webhook Event request sent to your webhook's URL. These headers can be used to identify which merchant and gift card program the webhook event is coming from.
| HTTP Header Name | Header Description |
|---|---|
| X-LOOPZ-MERCHANT-ID | The identifier of the merchant of the gift card program. |
| X-LOOPZ-PROGRAM-ID | The identifier of the gift card program the event is coming from. |
| X-LOOPZ-WEBHOOK-TOPIC | The topic of the webhook event. |
| X-LOOPZ-WEBHOOK-SUBSCRIPTION-ID | The ID of the webhook. |
You can find the merchant ID and program ID by using the authorization status endpoint
Example Webhook Request
The following request shows how Loopz sends a location.updated webhook event to your webhook's URL
curl -X POST [your-webhook-url] \
-H "Content-Type: application/json"
-H "X-LOOPZ-MERCHANT-ID: [merchant-id]"
-H "X-LOOPZ-PROGRAM-ID: [program-id]"
-H "X-LOOPZ-WEBHOOK-TOPIC: [webhook-topic]"
-H "X-LOOPZ-WEBHOOK-SUBSCRIPTION-ID: [webhook-subscription-id]"
--data "
{"id": "72b8ebd8-ea23-44a5-b8d1-b727d80ecd1a", "name": "My Location", "status": "ACTIVE", "type": "PHYSICAL"}
"