To receive webhook notifications, you must first register the URL where the webhook should be sent and the triggering event. When the event occurs, the API will send an HTTP request containing the notification to the specified URL. If a valid HTTP response is not received, the API will retry up to 15 times on an exponential backoff schedule. A 200 or 202 response code is expected. A webhook response should only be determined by your servers ability to receive the incoming notification. Any backend processing or handling of the actual event should not factor into the returned HTTP response. All changes to API resources will generate webhooks. Your application may choose to react to the subset of events it finds relevant. For example, if your application creates ACH transfers, it may choose to react to webhook events notifying that the status of an ACH transfer was changed. Webhook objects have a status: if they are enabled, then a notification will be issued to the URL. Any other status (error, disabled) will not issue a notification. To re-enable a webhook that is in error or disabled status, update the status field to enabled.

​
Webhook Ordering

We cannot guarantee that webhooks will be received in order. In practice, events that have a significant time gap between them will be received in order. However, when two events are only a few milliseconds apart, the one sent first may arrive second. In a production environment, you should encounter this less frequently, but it is still possible to receive an out-of-order webhook. If you query the API using the object ID provided in the webhook payload, you will always receive the latest information.

​
Webhook Payloads

POST https://example.application.com/notify

{
  "event": "ach.update",
  "op": "update",
  "id": "ach_01123456789",
  "url": "https://api.treasuryprime.com/ach/ach_01123456789"
}

​
Validating Webhooks

Validating that webhooks originate from Treasury Prime ensures that a webhook notification is authentic. If a webhook object has been created with the basic_user and basic_secret fields, notifications from Treasury Prime will include an additional Authorization header that is the base64-encoded value of {basic_user}:{basic_secret}. When the base64 header matches the value your application expects, the request is authentic.

​
Webhooks in error status

If there are too many bad responses when sending notifications to a webhook’s URL within a short time, the webhook will be put into status error. No new webhooks will be issued on webhooks in error status. This happens only for a high volume of failed responses, and is done to prevent other webhook notifications from slowing down. A webhook can be changed back to enabled status by updating the status field to enabled. This will reset the webhook and new webhooks will now be issued.

​
Smart Webhook Retries

Organizations can enable an automatic retry logic for webhook messages that receive non-200 HTTP responses. If a webhook message fails (receives a non-200 response), our system will automatically retry sending the message.
  • Benefits
    • This ensures that any missed notifications are automatically retried
  • How to Enable
    • For this to be enabled at a Fintech, your corresponding Bank will need to provide approval. Please reach out to your Relationship Manager or Treasury Prime Support