Webhooks
Create, edit, delete webhooks.
The Webhooks page (found under 'Settings') in the ZAP-APP allows you to manage webhooks and view any historic executions.
What is a webhook?
A webhook is a way for an application to provide other applications with real-time information. Webhooks provide a powerful mechanism for integrating different services and enabling automation in a streamlined manner.
Any created webhooks also have the option to view the logs giving you more insight into any successes and errors.
Adding a Webhook
To add a webhook, simply click 'Add New Webhook'. A slide out will then appear allowing you to create your webhook. You'll have the ability to set the following values.
Name - An easily recognisable name for the webhook being created. Target URL - The URL endpoint to which events should be sent. Event Trigger - When the specific event happens in the ZAP APP, it triggers the webhook. Basic Auth Username - The username built into the HTTP protocol. Basic Auth Password - The password built into the HTTP protocol. HTTP Headers - These let you and the server pass additional information with an HTTP request or response. They're most often used for authentication purposes. Status - Determines if the webhook is active or inactive.
Once you're done, click 'Create Webhook' and your details will be saved.
Event Triggers
When creating a webhook, choose the event that should send the request.
The examples below show the typical JSON body for each event. Use your webhook logs to confirm the exact values returned for your account.
New Submission
This triggers whenever a new submission is created in ZAP-POST. This includes submissions added in the app via CSV uploads, integration submissions and submissions sent through the API.
Records Rejected
This triggers during the 'Data cleanse' phase of the ZAP process. During this stage we will execute any end limit checks as well as any address checks. It fires when a record fails validation , address check or hits a send limit and is removed from the send.
Please note, the PAF, Cleanse and Sent Limiter processes are sent as independant Records Rejected Webhooks.
Submissions Sent
This triggers when the final composed mail files are released to print and mail.
Zap Returned
This triggers when a mailed ZAP is returned to sender after a delivery attempt.
QR Code Scanned
This triggers when a recipient scans a tracked QR code on the mailed ZAP.
Testing Webhooks
In order to test a webhooks effectively without needing to meet the criteria of each webhook trigger, integrators can simply select the Test Webhook
This will fire the webhook to your configured target using a dummy set of data which will enable you to test the receiver is working as intended.
Editing Webhooks
To edit a webhook, click on the edit icon on the webhooks page and you can amend any details you need.
Deleting Webhooks
To delete a webhook, click on the bin icon on the webhooks page, you'll see a pop up asking if you're sure you want to delete.
Webhook Logs
To view the logs for one of your webhooks, click on 'View' from the webhooks page. This will then give you an overview of all logs for that webhook with a quick visual of the Status Code for each event.
You can filter this page based on Target URL, Status Code, From and To Dates and Time. Click the filters expand control to see the different filter options
To see the request and response for each log, click on the view logs icon.
Requests
When viewing a log, you'll be able to see the request header, a webhook request header is part of the HTTP request sent to a specified URL endpoint when an event triggers the webhook. These headers contain data about the request and help ensure that the receiving server can interpret the incoming data correctly and securely.
You'll also be able to view the request body, a webhook request body contains the actual data payload sent from the source application to the receiving server when an event triggers the webhook. This payload includes detailed information about the event and any relevant data associated with it.
Responses
You're also able to view the webhook response header, A webhook response header is part of the HTTP response sent by the server that receives a webhook request. These headers provide information about the response and can include status information, content type, and other metadata.
A webhook response body is the data returned by the server receiving a webhook request. It provides feedback about the result of the webhook processing.
Replaying a Webhook Request
If you were unable to process a webhook when it was originally triggered or simply wish to rerun a selection of webhooks this can be done via the logs screen.
Replaying a single webhook
In order to replay a single webhook you can select the expansion menu and select the Replay webhook option.
Replaying multiple webhooks
To replay multiple webhooks you can either select the webhooks you wish to fire and click "Replay Selected Webhooks"
You can also reprocess any webhook that matches the current filter criteria configured for the view. To do this configure your required filters and then select "Replay all matching filters"
In either scenario click replay when the confirmation window shows.
After that your webhooks should be replayed based on the current configuration. This is important since it allows you to cycle credentials or update incorrect URLs without any issue replaying old webhooks.
Last updated
Was this helpful?