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:

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.

{
            "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

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
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.
Once the reply is configured you should verify it via API:

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

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.

To delete subscription use the following API:

DELETE http://yourproject.vouchery.io/api/v2.0/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

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

Create a new subscription via

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

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

Then paste the verification_code into the response body and save.

Now you can verify the URL via

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

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