> For the complete documentation index, see [llms.txt](https://docs.txn.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.txn.io/api-basics/webhooks.md).

# Webhooks

Txn supports webhooks for the following transaction types:

* [Invoices](https://docs.txn.io/invoices/invoice-webhooks.md)
* [Payouts](https://docs.txn.io/payouts/payout-webhooks.md), created through the API or in the dashboard
* [Channel deposits](https://docs.txn.io/channels/channel-webhooks.md)
* [Exchange](https://docs.txn.io/exchange/exchange-webhooks.md)
* Crypto deposits received at your account addresses
* [Bank deposits](https://docs.txn.io/fiat-settlements/bank-deposit-webhooks.md) and [bank withdrawals](https://docs.txn.io/fiat-settlements/bank-withdrawal-webhooks.md)

Webhooks are triggered each time the state of a transaction is updated. [Webhook events](https://docs.txn.io/api-basics/webhooks/webhook-events.md) lists, per subscription, what triggers a message and what its payload contains.

You can configure your webhook URLs on the **Developer Tools → Webhooks** tab in your Txn account. Click **Add Webhook**, enter a name and your endpoint URL, optionally associate API keys, and choose which operations trigger the webhook. Creating and deleting a webhook URL asks for the 6-digit code from your authenticator app.

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-c5df6f4d500f99108500777a7cb1b53d30f7cc62%2Fwebhook1.png?alt=media" alt="Webhooks tab"><figcaption><p>Developer Tools → Webhooks</p></figcaption></figure>

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-83eb9cf0172b07dcb12b7e52c65c64c41558dcfc%2Fwebhook2.png?alt=media" alt="Create Webhook"><figcaption><p>Enter a name and your endpoint URL, optionally associate API keys, and choose which operations trigger the webhook</p></figcaption></figure>

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-b1c8a4fdf20e20ca085c8e471dffcbe3c483c0cf%2Fwebhook3.png?alt=media" alt="Save the webhook secret key"><figcaption><p>Copy and save the secret key — it is shown only once and is used to verify webhook signatures</p></figcaption></figure>

## Associating API keys with webhook URLs

When creating or editing a webhook URL, you can associate one or more API keys with it. All transaction events for resources created by an associated key — invoices, payouts, channels, exchanges, and deposits — are routed to that endpoint.

This lets you route events from different parts of your integration to different endpoints. For example, you could direct invoice events to one service and payout events to another by using separate API keys, each associated with its own webhook URL.

Which messages a webhook URL receives depends on whether API keys are associated with it:

* **No API keys associated:** the URL receives every message for the subscriptions you selected, for your whole company, whether the resource was created through the API or in the dashboard.
* **API keys associated:** the URL receives messages only for resources created by those keys. Resources created in the dashboard, and crypto deposits to your account addresses, are not created by an API key, so their messages go only to URLs with no API keys associated.

{% hint style="danger" %}
**Deleting an API key stops routing for everything that key created.**

Every resource — invoice, payout, channel, and so on — is permanently linked to the API key that created it. Webhook URLs associated with that key stop receiving messages about its resources once the key is deleted. Only webhook URLs with no API keys associated keep receiving them.

**Example:** API key A is associated with webhook URL B. A channel is created using key A. Key A is later deleted and key D is created. Even though key D may be associated with URL B, the channel was created by key A, so its events no longer route to URL B. A webhook URL with no API keys associated still receives them.

**When rotating API keys:**

1. Create the new API key first.
2. Associate the new key with the relevant webhook URLs **before** using it to create any resources.
3. Resources already created by the old key stop routing to the URLs associated with it as soon as the old key is deleted, and they cannot be reassigned to a new key. If you need their events afterwards, keep a webhook URL with no API keys associated.
   {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.txn.io/api-basics/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
