How to configure webhooks

It is possible to receive notifications on various Vouchery system actions through Subscription API which works as a webhook interface.

Following events are supported:

* voucher_redeemed

* voucher_batch_created

* voucher_created

* voucher_redemption_rejected

* budget_limit_reached

* voucher_redemptions_limit_reached

Configuration

To enable notifications, please follow these steps:

1. Create new event subscription via API:

   POST http://yourproject.vouchery.io/api/v2.0/subscriptions

   In the request body, you need to provide a list of events that you want to listen on and a callback_url which is an HTTP endpoint in your system where events will be delivered.

   Make sure you have full control over this endpoint. You will need to adjust the GET response in the verification process.

   Example request body:

   {
           "callback_url": "https://<your_server_url>",
           "events": [
               "voucher_redeemed", 
               "voucher_batch_created",
               "voucher_created", 
               "voucher_redemption_rejected",
               "budget_limit_reached",
               "voucher_redemptions_limit_reached"
           ]
   }
   

   NOTE: Number of subscriptions is limited to 10 per project. You should DELETE old subscriptions

2. In the response, you should receive a subscription ID and verification_code that will be used to verify that provided callback_url is valid and reachable from vouchery.io

3. Now you should configure your callback_url GET response so that it will reply to the verification request. The reply should have text/plain MIME type and contain only verification_code in the body.

4. Once the reply is configured you should verify it via API:

GET http://yourproject.vouchery.io/api/v2.0/subscriptions/{subscription_id}/verify

5. After a successful response (204) the subscription is activated. You should start receiving POST requests on callback_url in the following format:

   {
       "type": <event_type>,
       "data": <event_details>
   }
   
   

   NOTE: HTTP 400 (Bad Request) reply usually means that your reply is malformed / contains invalid verification_code. You will not receive any events until the callback_url is verified.

   After successful verification, you can disable the GET handler.

6. To delete subscription use the following API:

DELETE http://yourproject.vouchery.io/api/v2.0/subscriptions/{subscription_id}