Webhooks provide a powerful method to track appointments and to take actions within external systems. Review these best practices to ensure your webhooks remain secure and function seamlessly with your integration.

Retry logic

If an error occurs when sending the webhook (a non-2xx response is received, the connection is lost or the request times out), we automatically try again with a delay. The current retry logic is as follows:

• A webhook is sent and will time out after 3 seconds.
• The webhook is re-sent with a delay of 2 seconds and will time out after 5 seconds.
• The webhook is re-sent with a delay of 10 seconds and will time out after 30 seconds.
• After three errors, the webhook is not retried.

This retry logic can thus survive an unavailability of the receiver of 50 seconds, including successful processing time.

Event handling

Handling webhook events correctly is crucial to making sure your integration's business logic works as expected.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the id of the event you've processed, and then not processing already-logged events. The id is guaranteed to be unique for a single event and remains the same during retries.

Order of events

Pexip Engage does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of these events in this order and should handle this accordingly. One way of doing this is by logging specific time-based resource properties, included in the payload, and then not processing events that have a value for this time-based resource property which is before an already logged event. For example, each change to an appointment will result in a updated updatedAt timestamp property of the appointment. This can be used to compare incoming events with already logged events for the same appointment id.

Security

Keeping your endpoints secure is critical to protecting your customers' information. Pexip Engage provides several ways for you to verify events are coming from Pexip Engage in a secure manner.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Pexip Engage validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Verify events are sent from Pexip Engage

Verify webhook signatures to confirm that received events are sent from Pexip Engage.

To do this, we have added a number of extra headers.

• X-Pexip-Signature-v1
• X-Pexip-Request-Timestamp

The signature header contains the HMAC SHA-256 hash of the request. To validate if the request header is valid for the receiving payload, the receiver should first validate the timestamp of the request. The timestamp should not be older than 5 minutes. Next, the receiver needs to calculate the same hash using the secret token of the webhook configuration. The hash is calculated using the following format:

${webhookConfiguration.method}${webhookConfiguration.url}${payload}${timestamp}

Additionally, Pexip Engage sends webhook events from a set list of IP addresses. Only trust events coming from these IP addresses. These IP addresses are:

• Production: 20.73.202.25
• Staging: 20.76.6.66