WebHooks in Avidon provide a powerful mechanism to integrate real-time events with your systems. This document details how to set up and manage WebHooks for your application.

Overview

Avidon WebHooks post events to a client-defined HTTPS endpoint, allowing your applications to respond to events as they occur in real-time. This is useful for syncing data, triggering workflows, or updating your application state in response to user actions on the Avidon platform.

Configuring Your WebHooks

To configure WebHooks, you need to specify the HTTPS endpoint that will receive the WebHook events. This endpoint must be prepared to handle requests according to the following specifications:

• Endpoint URL: The URL must be HTTPS for secure transmission.
• Response Requirement: The endpoint should return an HTTP 204 status code within 5 seconds to acknowledge successful receipt of the event.
• Security: Note that no additional security options are provided; ensure your endpoint is secured appropriately.

See the WebHooks Section on the Data Management page.

Event Delivery

When an event occurs, our system will send a POST request containing a JSON payload to the registered endpoint. The payload includes a list of PortalEvent objects. For detailed model specifications, refer to PortalEvent Model.

Response Time Requirement:
Your endpoint must respond with an HTTP 2xx status code within 5 seconds of receiving the request. To ensure reliable event delivery and avoid retries, you should immediately acknowledge the request and offload any processing to background tasks or worker queues.

Handling Failures

If the WebHook fails (due to timeout, a non-2xx status code, or network issues), the following retry mechanism will be applied:

• Retry Strategy: An exponential backoff approach is used to retry delivery.
• Maximum Retry Duration: Retries will continue for up to 24 hours from the time of the initial attempt.
• Support idempotency: Ensure your webhook handler is idempotent in case of repeated deliveries.

Best Practices

• Endpoint Performance: Ensure that your endpoint can handle the expected load and respond within the required 5 seconds.
• Error Handling: Implement robust error handling and logging to troubleshoot and resolve issues that may arise during WebHook processing.
• Security Considerations: As WebHooks will be pushing data to your endpoint, ensure it is secured appropriately to prevent unauthorized access.

Additional Resources

For any further questions or support, please refer to our support portal.