Callback endpoints requirements

To ensure reliable communication, the callback_url endpoints provided by vendors must adhere to the following requirements. These guidelines outline how our services interact with the webhook callbacks and what is expected from the vendor's callback endpoint implementation.

Timeout

• Response Time: Vendor callback endpoints must respond to webhook requests within 5 seconds.
  • If no response is received within this timeframe, our service will consider the webhook request as failed and may retry delivery.
  • This ensures that the webhook system does not stall while waiting for a response.

Response Codes

• 200 OK: The callback endpoint must return a 200 OK status code to confirm that the event payload was successfully received and processed.
• 4xx Client Error: Any 4xx status code indicates a client-side error on the vendor's endpoint. Examples include:
  • 400 Bad Request: The request was malformed or invalid.
  • 401 Unauthorized: Authentication failed or was not provided.
  • 404 Not Found: The requested resource could not be found.
  • Our service will not retry webhook delivery if a 4xx response is received, as it is considered a non-recoverable error.
• 5xx Server Error: Any 5xx status code indicates a server-side issue on the vendor's endpoint.
  • Repeated 5xx responses may lead to temporary suspension of webhook delivery until corrective actions are taken.
  • Our service may retry delivery based on the retry strategy outlined below.

Retry Strategy

Retry on Failure

• Failure Handling: If a webhook delivery fails due to a timeout or a 5xx server error, our service will retry the request after a set interval.
  • Vendor endpoints should be prepared to handle repeated requests without causing adverse effects, such as duplicate actions.

Exponential Backoff

• Backoff Mechanism: The retry mechanism may use an exponential backoff strategy, where the delay between retries increases with each attempt.
  • Vendor endpoints should ensure they can handle retries gracefully without duplicating actions or side effects.

Handling 429 Too Many Requests

• Retry Policy: When a 429 Too Many Requests response is received, our service will check for a Retry-After header:

  • With Retry-After Header: If the header is present, our service will wait for the specified time before attempting to retry.
  • Without Retry-After Header: In the absence of a Retry-After header, our service may implement an exponential backoff strategy, with a limited number of retries. This helps to avoid overwhelming the vendor's endpoint and respects rate limits.
  • Graceful Handling: Excessive 429 responses may lead to temporary suspension of webhook retries until the vendor indicates they are ready to receive requests again.

• Vendor Requirement: Vendors must include a Retry-After header when responding with a 429 Too Many Requests status code. This header should specify the duration (in seconds) that our service should wait before attempting to send the request again.

Idempotency Requirements

Idempotency

• Consistent Processing: Vendor callback endpoints must be idempotent. If the same event is delivered multiple times due to retries or other factors, the endpoint must process it in a way that avoids unintended side effects.
  • Vendors should implement a mechanism, such as tracking the event_id, to ensure that duplicate events are not processed more than once.

Rate Limiting

Rate Handling

• Burst Management: Vendor endpoints should be capable of handling bursts of incoming requests, especially when multiple events are triggered within a short timeframe.
  • Implementing rate limiting strategies is recommended to avoid overwhelming the server and ensure that incoming webhook requests are processed effectively.

Graceful Degradation

• Overload Protection: In scenarios of excessive load, the endpoint should degrade gracefully.
  • When limits are exceeded, the endpoint should return appropriate 429 Too Many Requests responses and maintain stability for other ongoing operations.