Skip to main content
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: After the third retry fails, the delivery is marked as failed and no further attempts are made.

​
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.