Webhooks
Overview
The webhook system provides real-time notifications when key events occur within your subscriber and campaign data. You can create multiple webhooks for each endpoint and select a combination of events to suit your application's needs. Each webhook comes with its own unique secret that you must use to verify (and if necessary, decrypt) the payloads sent by the software.
Our webhook implementation follows industry best practices, to ensure secure and reliable delivery of events.
Available Webhook Events
You can subscribe to any of the following events. Each event is provided in both English and Dutch:
Subscriber Events
Subscriber Created (SUBSCRIBER.CREATED)
Triggered when a new subscriber is added to the system.
Subscriber Subscribed (SUBSCRIBER.SUBSCRIBED)
Occurs when a subscriber successfully opts in to receive communications.
Subscriber Unsubscribed (SUBSCRIBER.UNSUBSCRIBED)
Fired when a subscriber opts out or is removed from the subscription list.
Subscriber Bounced (SUBSCRIBER.BOUNCED)
Triggered when an email sent to a subscriber bounces due to delivery issues.
Subscriber Updated (SUBSCRIBER.UPDATED)
Indicates that the subscriber’s details or preferences have been modified.
Campaign Sent (SUBSCRIBER.CAMPAIGN_SENT)
Occurs when a campaign email is successfully delivered to subscribers.
Campaign Opened (SUBSCRIBER.CAMPAIGN_OPENED)
Fired when a subscriber opens a campaign email.
Campaign Link Clicked (SUBSCRIBER.CAMPAIGN_LINK_CLICKED)
Triggered when a subscriber clicks a link within a campaign email.
Subscriber Email Changed (SUBSCRIBER.EMAIL_CHANGED)
Occurs when a subscriber’s email address is updated.
Subscriber Deleted (SUBSCRIBER.DELETED)
Fired when a subscriber is removed from the system.
Campaign Events
Campaign Created (CAMPAIGN.CREATED)
Triggered when a new campaign is initiated.
Campaign Updated (CAMPAIGN.UPDATED)
Occurs when the details of an existing campaign are modified.
Campaign Deleted (CAMPAIGN.DELETED)
Fired when a campaign is removed from the system.
Setting Up Your Webhooks
You can register several webhooks for a single endpoint. This allows you to organize notifications by event type or direct them to different components of your system.
Event Selection:
When creating a webhook, simply choose the specific events from the list above that you wish to receive. This targeted approach ensures that you only get the notifications you need.
Webhook Secret
Each webhook is assigned a unique secret during creation. This secret plays a critical role in verifying the authenticity of the payload.
Use the secret to validate that the incoming webhook request is truly from the software.
Payload Decryption:
If the payload is encrypted, the secret is used to decrypt it, ensuring secure access to the event data.
Verifying the signature of incoming webhooks
Here you will find the best way to decrypt a webhook secret for a PHP application:
Best Practices for Webhook Integration
To maximize security and reliability when integrating our webhooks, please consider the following best practices:
Verify the Signature
Always use the provided secret to verify the signature on incoming webhook requests. This helps ensure that the data is authentic and untampered.
Validate the Payload
Check that the payload is in the expected format and contains all necessary information before processing it.
Acknowledge Quickly
Respond with a 2xx HTTP status code as soon as your endpoint receives an event. Quick acknowledgments help prevent unnecessary retries.
Implement Idempotency
Since webhook events may be delivered multiple times (especially during retries), design your processing logic so that each event is handled safely and only once.
Secure Your Endpoint
Use HTTPS to ensure that data is encrypted in transit.
Consider additional security measures such as IP whitelisting to restrict access to your webhook endpoint.
Log Webhook Activity
Maintain detailed logs of incoming webhook events. This will aid in troubleshooting and help you monitor the health of your integration.
Retry Strategy
The webhook system includes a robust retry strategy to ensure reliable event delivery:
Automatic Retries:
If your endpoint does not return a 2xx status code, the software will automatically attempt to resend the event.
Exponential Backoff:
The retry mechanism uses an exponential backoff strategy, meaning the delay between successive retries increases. This helps prevent overwhelming your server during periods of downtime.
Idempotent Handling:
Due to the possibility of receiving duplicate events (especially as a result of retries), ensure that your endpoint is capable of processing duplicate notifications without adverse effects.
Conclusion
The webhook system is designed to offer flexibility, security, and reliability in notifying your application about important subscriber and campaign events. By carefully selecting the events you need, securing your endpoints, and following these best practices, you can integrate webhook notifications seamlessly into your workflow.
For further details or support, please refer to our contact our support team.
Updated about 2 months ago