At the start of 2024, Voucherify introduced a new approach to webhook notifications. The changes to the webhook payload include modifications to key fields and the overall structure. The new approach is a breaking change that requires development effort to switch to the new version of the payloads.
While we recognize the inconvenience of breaking changes, these updates are designed to enhance the overall reliability and performance of Voucherify webhook services. We appreciate your understanding as we work to deliver a more robust and advanced platform.
Effective Date of Change: March 31, 2024.
As these changes are breaking, it is crucial that you update your integration to accommodate the new webhook payload structure before the effective date mentioned above. Failure to do so may result in disruptions to your webhook processing.
Webhook Changes Detailed
The changes to the webhooks consider the difference in the payload only. Here is the comparison between the overall structure of the redemption.succeeded event.
| V2018-08-01 keys | Explanation | V2024-01-01 keys | Explanation | Comparison |
|---|---|---|---|---|
id | ID of the event | id | The ID of the webhook sendout | The purpose of the key changed |
object | Always set to event | - | Key was dropped | Key dropped |
webhook_id | ID of the webhook sendout | - | Changed the key to id | Key renamed |
project_id | ID of the project associated with the webhook | project_id | ID of the project associated with the webhook | No change |
created_at | Original sendout date and time | created_at | Original sendout date and time | No change |
type | Name of the event | type | Name of the event | No change |
data | Contains the data associated with the event | data | Contains the data associated with the event | Complete redesign of the data object |
| - | - | source | Object containing the webhook or distribution ID with the target url | Introduced |
metadata | Contains additional details about the webhook | - | Object dropped | Object dropped. The object contained limited information regarding the source of the event. The information was moved to the source object in v2024-01-01 |
| - | - | event | Identifies the original trigger of the webhook | Object introduced |
Webhook v2024-01-01 Structure
The following table contains brief description of the new webhook structure.
More details about the webhook structure and payload can be found in the project setting webhooks documentation and distribution webhook documentation.
| Key | Explanation | Example data |
|---|---|---|
id |
The sendout ID of the webhook | whs_0e4120a21947463292 |
project_id |
ID of the project associated with the webhook | proj_lurN555 |
created_at |
Original sendout date and time | 2024-02-06T08:39:59.188Z |
type |
The event's name (distribution webhooks) or type (project setting webhooks) | Your name of distribution OR, e.g.,customer.rewarded.loyalty_points |
data |
The webhook's unified information that, depending on the type of the webhook, can consist of:
The data will consist only of the objects relevant for the webhook notification. Please refer to the relevant section in the webhook documentation to retrieve the new webhook structure and sample payload. |
|
source |
Webhook or distribution ID. |
"source": {
"id": "wh_55555",
"object": "webhook",
"target_url": "{{your.webhook.target.url}}"
}
|
event |
Identifies the original trigger of the webhook. |
"event": {
"id": "evcus_55555",
"type": "customer.rewarded.loyalty_points",
"created_at": "2024-02-06T08:39:59.188Z",
"entity_id": "cust_55555",
"group_id": "v-55555",
"event_source": {
"channel": "INTERNAL"
}
}
|
Migration Procedure
To migrate your existing webhooks, follow the procedure below. Please note that your approach to the migration can be different; consider your developer team's input.
- Create a new project in Voucherify or use one of your existing sandbox or UAT purpose projects.
- Go to Project Settings.
- Scroll down to the Webhooks section.
- Switch your webhook definitions to v2024-01-01.
- For each v2018-08-01 webhook you have used so far, perform an action that triggers the v2024-01-01 webhook.
- Test the new webhook configuration and adjust your integration accordingly.
- Change to your production project and switch to the new webhooks in Project Settings.
Important notes
- On April 1st, 2024, Voucherify team members will start manually switching accounts to the new webhook definitions individually. If the webhooks are not switched to the new version, Voucherify team members will reach out to the account owners to ask about the webhook migration status. If you do not respond to this communication, the webhook definitions may be changed to version v2024-01-01 within the next few days. If you need more time to switch, please contact [email protected] immediately.
- There are significant changes to payloads in webhook v2024-01-01. Review these changes closely by testing webhook sendouts and reading webhook documentation.
- Once you switch to version v2024-01-01 on your production project(s), you can switch back to v2018-08-01 until March 31, 2024.
- If the new webhooks miss data that is crucial to your integration, reach out to [email protected] and provide details about your case and expectations.
- If, once in the production project, you find that the webhook definitions do not conform to your new format, please adjust your integration accordingly and contact [email protected] to resend the webhooks. Voucherify’s team can resend webhooks triggered no longer than 14 days ago.
Benefits of Switching to v2024-01-01 Webhooks
The new webhooks bring a couple of improvements to the Voucherify platform.
With the new generic approach to the structure of the payloads, it is easier to maintain the new payload structure, making the integration robust. The data object always reuses the same generic objects associated with the event.
The new structure is the first step to introducing a Custom Webhook builder. The builder will allow you to translate the webhook payload into an API request to external systems, so you will not need middleware between the two systems.
Also, the v2024-01-01 webhooks have a separate log. In the Voucherify Dashboard, go to the Audit log and the Webhook sendouts tab.
In the Webhook Sendouts log, you can see the status of the sent webhooks, filter the results, preview the sent payload, and retry sending the webhooks again.
Documentation of the changes and support
We understand that adapting to changes can be challenging, so we are here to assist you throughout this process. Please refer to regularly updated documentation, which outlines the specifics of the new payload structure.
If you encounter any issues or have questions during this transition, Voucherify support team is ready to help. Reach out to support at [email protected].