Best Practices & Deduplication

These are the essential security and implementation practices for building secure, reliable webhook integrations.

Security

• Always use a secure (HTTPS) URL. HTTP connections are unencrypted and vulnerable to man-in-the-middle attacks.
• Use an authentication method (BEARER, API_TOKEN, or BASIC_AUTH) when creating your webhook, to prevent unauthorized requests.
• Validate the event structure and content before processing: check that required fields are present and have the expected type.

Implementation

• Acknowledge receipt immediately with a 200 OK. Tonder has a 30-second timeout; respond first, then process business logic in the background.
• Use metadata.external_id to deduplicate. Store processed IDs temporarily (24-48 hours) and check against them before processing new events — the retry mechanism may send the same event multiple times.
• Keep detailed logs of the full payload, processing status, and errors, with timestamps and event IDs.
• Handle errors gracefully. Wrap processing in try-catch blocks so a failed webhook doesn't bring down your whole application.

Deduplication checklist

• Dedupe on metadata.external_id (works across Short + Long formats).
• Keep an idempotency_key index in your DB.
• Treat duplicate Pending + Success in Hybrid mode as intentional.
• Always verify final status via GET /api/v1/transactions/{id}/.
• Handle Declined for withdrawals as a terminal state.

Next steps