Configuring & testing Webhooks

Vouchery webhooks notifications

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

Webhooks configuration

To enable notifications, please follow these steps:

1. Create a new event subscription via API:

   POST https://yourproject.vouchery.app/api/v2.1/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.

{
            "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: The 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 https://yourproject.vouchery.app/api/v2.1/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 the subscription use the following API request:

DELETE https://yourproject.vouchery.app/api/v2.1/subscriptions/{subscription_id}

Testing webhooks

You can test our Vouchery webhooks subscription mechanism without any server. To do so, use online webhook test tools (e.g. https://webhook.site ). Make sure to modify the GET reply body so that it contains the verification_code and then verify the URL before you start receiving events.

Example for https://webhook.site

1. When you open the website you should see a unique URL for your temporary server. Use that as the callback_url

2. Create a new subscription via

POST https://yourproject.vouchery.app/api/v2.1/subscriptions

3. In response, you should get verification_code. Edit your temporary server response:

4. Then paste the verification_code into the response body and save:

5. Now you can verify the URL via

GET https://yourproject.vouchery.app/api/v2.1/subscriptions/{subscription_id}/verify

6. Your received events should start showing on the list (under REQUESTS)