> ## Documentation Index
> Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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

<CodeGroup>
  ```bash bash theme={null}
  POST https://example.application.com/notify

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

## 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

## Webhook Webhooks

You can register a webhook to receive notifications about updates to other webhooks. To do so, subscribe to the `webhook.update` event:

<CodeGroup>
  ```json theme={null}
  {
    "event": "webhook.update",
    "url": "https://example.application.com/notify"
  }
  ```
</CodeGroup>

Once registered, your endpoint will receive notifications in the following format:

<CodeGroup>
  ```json theme={null}
  {
    "event": "webhook.update",
    "op": "update",
    "id": "webhook_01123456789",
    "url": "https://example.application.com/notify"
  }
  ```
</CodeGroup>

This is particularly useful for monitoring when a webhook enters an `error` or `disabled` status.