Review these best practices to ensure the security and efficiency of your webhook integration.
Your endpoint should promptly return a successful 2xx status code before initiating any complex operations that might cause a timeout. For example, send a 200 OK response immediately, before handling tasks like marking a customer invoice as paid in your accounting system. Note that our webhook calls will time out after 10 seconds; if you return a 2xx status after this period (e.g., at 11 seconds), the webhook call will be marked as failed and retried later.
HTTPS URLs are required in both testing and live modes. Riverty ensures a secure connection to your server before delivering webhook data. To enable this, your server must be properly configured to support HTTPS with a valid server certificate.
Webhook endpoints might sometimes receive the same event multiple times. To prevent handling duplicate events, ensure your event processing is idempotent. One approach is to log the events you’ve already processed and avoid processing any events that have been logged. This can be done using the unique ID of the message, present in all the messages we send.
Configure your handler to process incoming events using an asynchronous queue. Handling events synchronously can create scalability issues, especially during high-volume periods—like end-of-month invoice consolidations. Asynchronous queues allow your system to process multiple events concurrently at a manageable rate, improving performance and reliability.
To decode the signature and verify that the event was sent by us, we generate a unique key when you configure a webhook endpoint. Each endpoint has its own unique shared secret. Store this secret securely. If you have any security concerns or need the secret refreshed, please contact our integration manager, and we will assist you.
A replay attack happens when an attacker captures a legitimate payload and its signature, then retransmits them. To prevent this, we include a timestamp in the Riverty-Signature header. This timestamp is part of the signed payload and is verified by the signature, preventing an attacker from modifying the timestamp without invalidating the signature. If the signature is valid but the timestamp is outdated, you can discard the payload.
Do you find this page helpful?
