Best practices for handling webhooks

To facilitate seamless integration between your information system that receives webhooks and the Tuum system that sends them, we recommend following the best practices for webhook management outlined on that page.

Process incoming webhook requests

Always reply to the Tuum system promptly with an HTTP 200, 201, or 202 status code upon receiving the webhook, allowing your system to process the data at its own speed. This prevents Tuum from retrying the webhook and helps avoid duplicates.

Ensure proper handling of duplicates

The same event may occasionally be delivered more than once. This can happen if your endpoint does not respond in time, returns an error, or experiences temporary network issues. In such cases, the Tuum system automatically retries failed deliveries according to its retry policy.

To smoothly handle these exceptional situations, implement your webhook handler so that it is idempotent—safe to process the same event multiple times without changing the outcome.

1. Extract a unique identifier from each webhook payload (such as the notification ID) and use it to track which events you have already processed.

2. Store these processed IDs in your system: when a webhook arrives, first check whether the ID has already been seen; if it has, ignore the event as a duplicate.

3. Design your operations to be idempotent: any downstream actions, such as posting transactions, updating balances, or performing other state changes, should produce the same result even if they run multiple times with the same ID. For example, when recording a payment, the system should detect that a payment with the same ID already exists and skip creating a new one, preventing duplicates.

By following these recommended webhook handling practices, you will also make it easier to address other exceptional cases, such as resending unreceived webhooks.