# Webhooks

Webhooks allow you to automatically receive notifications about invoice status changes without having to constantly poll the API.

Notifications are sent to the URL you specify when creating an invoice – either in your Dashboard or via the API.

To start receiving webhooks, simply include the `webhook_url` parameter when creating an invoice, for example:

```json
"webhook_url": "https://example.com/webhook"
```

Webhooks are triggered whenever the invoice status changes to one of the following:

<table data-header-hidden><thead><tr><th valign="top">Status</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top">COMPLETED</td><td valign="top">The invoice has been paid and the funds have been forwarded to the merchant. For temporary address invoices only.</td></tr><tr><td valign="top">TIMEOUT</td><td valign="top">The invoice has expired. For temporary address invoices only.</td></tr><tr><td valign="top">AML_FAILED</td><td valign="top">The payment did not pass the AML check. The funds have been returned to the sender.</td></tr><tr><td valign="top">OVERPAID</td><td valign="top">Invoice has been overpaid and funds have been forwarded to the merchant. Temporary address invoices only.</td></tr><tr><td valign="top">UNDERPAID</td><td valign="top">Invoice has been underpaid and funds have been forwarded to the merchant. Temporary address invoices only.</td></tr><tr><td valign="top">ERROR</td><td valign="top">Invoice was processed with an error.</td></tr><tr><td valign="top">Static address payment</td><td valign="top">A payment on a static address invoice has been received and processed. Sent separately for each payment event.</td></tr></tbody></table>

Webhook payload format:

```json
{
  "id": 336575574,
  "status": "ACTIVE",
  "type": "SINGLE",
  "paymentURL": "https://app.goodpayments.io/payment/336575574",
  "amount": 10,
  "currencies": [
    "TRX",
    "USDT"
  ],
  "currencies_amounts": {
    "TRX": 33.402357,
    "USDT": 10
  },
  "transfer_amounts": {
    "input": {
      "TRX": 0,
      "USDT": 0
    },
    "output": {
      "TRX": 0,
      "USDT": 0
    }
  },
  "cost": null,
  "client_commission": true,
  "order_id": null,
  "address": "TRWvSiQzhSpLdRAmwDHKtgd7bZb2G2be53",
  "webhook_url": null,
  "redirect_url": null,
  "description": "",
  "merchant_contact": "@username",
  "target_wallets": {},
  "expired_at": "2026-03-17T11:59:07.515594+03:00",
  "created_at": "2026-03-17T11:29:07.518981+03:00"
}
```

| Name                | Type    | Description                                                                                                                                                                                                                                                                                      | Example                                         |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| id                  | integer | Unique invoice ID                                                                                                                                                                                                                                                                                | 123477361                                       |
| status              | string  | <p>Invoice status. Possible values:</p><ul><li><code>COMPLETED</code></li><li><code>TIMEOUT</code></li><li><code>ERROR</code></li><li><code>AML\_FAILED</code></li><li><code>OVERPAID</code></li><li><code>UNDERPAID</code></li></ul>                                                            | COMPLETED                                       |
| type                | string  | Invoice type. `SINGLE` – temporary address; `MULTIPLE` – static address                                                                                                                                                                                                                          | SINGLE                                          |
| paymentURL          | string  | Payment page URL                                                                                                                                                                                                                                                                                 | <https://app.goodpayments.io/payment/123477361> |
| amount              | number  | Invoice amount in USD                                                                                                                                                                                                                                                                            | 1                                               |
| currencies          | string  | <p>List of accepted tokens. Possible values:</p><ul><li><code>TRX</code></li><li><code>USDT</code></li><li><code>TRX, USDT</code></li></ul>                                                                                                                                                      | \["USDT", "TRX"]                                |
| currencies\_amounts | string  | Amount to be paid in each accepted token                                                                                                                                                                                                                                                         | "TRX": 3.6329                                   |
| transfer\_amounts   | string  | Actual received amount                                                                                                                                                                                                                                                                           | "TRX": 3.6329                                   |
| cost                | number  | Service fee charged for processing the payment                                                                                                                                                                                                                                                   | 6.5                                             |
| order\_id           | string  | Order identifier in the merchant's system                                                                                                                                                                                                                                                        | 12345                                           |
| address             | string  | Generated  payment address                                                                                                                                                                                                                                                                       | TBi3zPSQ8JszpkkgwZL4kZWDjXEZsi9Fze              |
| client\_comission   | boolean | <p>Flag that determines who pays the forwarding fee. Only for <code>SINGLE</code> invoice type.</p><ul><li>true – the fee is charged to the client. The invoice amount is increased by the fee, and the client pays the total amount.</li><li>false – the fee is paid by the merchant.</li></ul> | true / false                                    |
| webhook\_url        | string  | The URL to which goodPayments will send a webhook after the customer completes the payment                                                                                                                                                                                                       | <https://example.com/webhook>                   |
| redirect\_url       | string  | The URL where the customer will be redirected after completing the payment                                                                                                                                                                                                                       | <https://example.com/thank-you>                 |
| description         | string  | Order description: may contain any provided information related to the order                                                                                                                                                                                                                     | Payment for order #123                          |
| merchant\_contact   | string  | Merchant contact details                                                                                                                                                                                                                                                                         | @username                                       |
| target\_wallets     | object  | An object containing a list of addresses and the amount to be sent to each address (for invoices with type `MULTIPLE_TRANSFER`).                                                                                                                                                                 |                                                 |
| expired\_at         | string  | Invoice expiration timestamp                                                                                                                                                                                                                                                                     | 2025-11-23T14:28:57.786076+00:00                |
| created\_at         | string  | Invoice creation timestamp                                                                                                                                                                                                                                                                       | 2025-11-23T13:58:57.789617+00:00                |

A webhook is sent only once. If your server does not respond within 10 seconds, the webhook will not be resent. In this case, we recommend checking the invoice status manually via the API whenever needed.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://goodpayments.gitbook.io/docs/api-reference/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.