Guides
SupportAPI StatusSubscribe To Updates

Callbacks

Suggest Edits

Pliant uses HTTPS callbacks (also known as webhooks) to notify partners about specific events that occur within our platform.

Partners can subscribe to these callbacks via the API. Once subscribed, your system will be notified whenever the specified event type occurs.

Callback Structure

  • Callbacks are sent as HTTPS POST requests.
  • Each callback includes a structured body containing event-specific information.
  • Callbacks can be:

Each callback request contains the following HTTP headers to assist with identification and processing:

HeaderDescriptionExample Value
X-Organization-IdThe organization associated with the event.54e6e7e7-0c23-4a54-bccb-2d3ff2fd02df
X-Partner-Organization-Id(Optional) The partner’s reference to the organization.abcdf1234
X-Payment-Program-IdThe payment program related to the event.54e6e7e7-0c23-4a54-bccb-2d3ff2fd02df
X-Callback-IdUnique UUIDv4 for the callback. Useful for deduplication.12a03093-eaad-4ae5-9d8d-42e7f6f8b7c6
X-Callback-Created-AtUTC timestamp of when the callback was created. May be used to re-order delayed callbacks.2024-03-15T15:55:58.623375258Z

Callback Semantics

ℹ️

We only send the callback. It's up to you to ensure successful processing on your side.

Callbacks are delivered with at least once semantics. This means:

  • A callback may be sent more than once for the same event.
  • While we attempt to deduplicate events, due to the asynchronous and distributed nature of the system, duplicates cannot be fully avoided.
  • You should implement idempotent endpoints to safely handle repeated deliveries.

📘

95% of callbacks are delivered within 10 seconds of the business event. The remaining 5% may take up to 1–2 minutes, depending on system load and event sequencing.

Retry Strategy

If your system responds with a non-2xx HTTP status code, Pliant will retry the callback automatically:

  • We do not follow redirects (e.g., 301, 302).
  • Retry duration: up to 24 hours.
  • Retry pattern:
    • First hour: retries every few minutes
    • Hours 2–23: once per hour
  • After 24 hours: the callback is marked as failed
  • You can request a manual retry by providing the callback ID(s) and the desired timeframe.

Important Notes

Callbacks reflect events in a fully asynchronous system. This means:

  • Order is not guaranteed — callbacks may arrive out of sequence.
  • Timing is not deterministic — most callbacks are fast, but some may be delayed depending on load and processing time.
  • Always use the X-Callback-Created-At timestamp if you need to reconstruct event order on your end.

Authentication

For information on securing your callback endpoints, please refer to the guide on Authenticated Callback usage.

Updated 1 day ago