Webhooks

Concept

A webhook (also known as a web callback or HTTP push API) is a method that allows your application to receive real-time notifications when an event occurs.

For example, if you send a contract for signature and need to be notified as soon as it is signed.

You could program a loop that checks the document status every 5 minutes for several days until you receive a response indicating that the document has been signed. This approach is not recommended, as it wastes a significant amount of resources each time you make an API call without a valid reason.

A better approach is to configure a webhook in the eZmax administration console to monitor a specific event. In this example, the event to monitor is DocumentCompleted from the Ezsign module. This way, as soon as the document is signed, a request will be sent to your server to notify you of the event that has just occurred.

When you configure eZmax to notify you of events, you must provide your server's URL as well as a backup email address. The URL provided must use HTTPS for security reasons.

Webhook Types

Look for the red indicators containing the word EVENT in the reference to see the webhook events currently available to subscribe to. If you need an event that is not available, please submit an enhancement request to Technical Support.

Important

• The event will be sent using a POST request.
• Your server must respond with an HTTP status code of 200, 202, or 204 to indicate to eZmax that you have accepted the message and that we will not attempt to send it again. If the server does not respond with a 200, 202, or 204 code, the message will be sent repeatedly until all attempts have been exhausted.
• The 200, 202, or 204 response must be returned within 30 seconds; otherwise, a timeout will occur and the event will be sent again according to the retry schedule.
• Make sure to secure the URL that receives your webhook requests to prevent someone from sending forged messages to your application. You can do this by providing a secure token in your URL, such as ?token=mysecuretoken1234, or by validating the webhook message signature.
• The User-Agent of the request will be Ezmax-Webhook.

Request Signing

You can enable request signing in the webhook configuration section. This adds an additional layer of security by including authorization, date, fingerprint, and signature headers in each request, which you can then validate. This method allows you to authenticate the request, prevent tampering, and protect against replay attacks.

The following HTTP headers will be added to each request:

• Ezmax-Authorization
• Ezmax-Date
• Ezmax-Fingerprint
• Ezmax-Signature

You can learn more about request signing in the Security section of the documentation.

Tests

In the eZmax administration module, you will find a "Test" button that you can use as many times as necessary to easily test your server code using a sample event.

Retries

eZmax will attempt to send the event to your server immediately, but will make several additional attempts if your server does not respond correctly for any reason (see the schedule below). Once all attempts have been exhausted, the event will be forwarded to the configured backup email address, using the same format as the webhook request. The email will contain the JSON request and HTTP headers in the same format as those used for the webhook. This way, you can send the request to your server using Postman, Curl or a similar tool.

Retry Schedule

This is the approximate schedule for retry attempts. Since a 30-second timeout is applied to each attempt, there may be a cumulative delay of up to 3½ minutes.

INFO

The following table applies only to actual automatic events. Test events and manual retries are attempted only once. In the event of an error or timeout, an email notification will be sent immediately.

Minutes after the previous step	Minutes after the event	Method
N/A	0	HTTPS
1	1	HTTPS
5	6	HTTPS
15	21	HTTPS
15	36	HTTPS
15	51	HTTPS
15	66	HTTPS
0	66	Email

Failed Attempt Report

If you do not receive the event after the first attempt, debugging information about each previous attempt will be included in the event body. You will be able to see the timestamp of each previous attempt, as well as the status code returned by your server, or an indication of a timeout if your server did not respond.