KeyPort delivers webhooks by sending an HTTP POST request to your registered endpoint. Understanding the delivery and retry behavior helps you build a reliable integration.
Delivery
KeyPort attempts the first delivery immediately after an event fires. Your endpoint must return a 2xx HTTP status code to acknowledge receipt. Any other response — including 3xx redirects, 4xx client errors, and 5xx server errors — is treated as a failed delivery.
Make your webhook handler idempotent. KeyPort may deliver the same event more than once if an initial delivery succeeds but a retry is already in flight. Use the event’s timestamp field and your own logging to detect and safely ignore duplicate deliveries.
Retry schedule
If a delivery fails, KeyPort retries at the following intervals after the previous attempt:
| Attempt | Delay after previous failure |
|---|
| Retry 1 | 1 minute |
| Retry 2 | 5 minutes |
| Retry 3 | 30 minutes |
Recommendations
- Respond quickly. Return a
2xx status as soon as you receive the request, before doing any processing. If your handler takes too long to respond, KeyPort may treat it as a timeout and retry.
- Process asynchronously. Enqueue the event and handle it in a background job rather than inline in the request handler. This keeps your response time short and separates concerns.
- Log deliveries. Record the event type, timestamp, and signature verification result on your side. This makes it easier to debug failed or duplicate deliveries.
