Webhooks

getpaid sends real-time notifications to keep track of the status changes in the system and let the platforms react to each event. To check the available notifications, please refer to the API reference, for example, check the invoices webhooks.

To receive webhooks, you need to provide an URL, usually in the field urls.webhook, in the API request that:

• Accepts POST requests with the webhooks request body. The content type of the body is application/json.
• Returns a 2xx HTTP status code within 30 seconds for successful requests. Any other status or timeouts code will be treated as a failure and the webhook will be retried following the retry policy. It is recommended to handle notifications in your system:
  • Asynchronously implementing a pattern similar to the inbox pattern to store the webhook right after receiving it to be able to acknowledge the reception to getpaid system.
  • Checking duplicates leveraging the id field, an unique notification identifier.
  • Ignoring the order of the notifications, as the getpaid system does not guarantee the delivery of notifications in any specific order.
• Supports HTTPS traffic with TLS 1.2.
• Optionally, consider adding getpaid's network to your firewall's allowlist.

Request body

The body of the webhook message is a JSON object with a similar structure where the type field defines the structure of the data that contains the specifics of each event. Please refer to the API reference to see the structure of each event.

{
  "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  "type": "invoice_paid",
  "version": "v2",
  "occurred_at": "2024-01-03T09:12:52.277Z",
  "data": {
    [...]
  }
}

Retry policy

When the reception of the webhook notification is not acknowledged returning a 2xx HTTP status code within 30 seconds, getpaid webhooks system assumes an unsuccessful delivery and implements the following retry policy until the maximum number of attempts is reached after 7 days:

Retry attempt	Between attempts	Since event occurred
1	2m	2m
2	5m	7m
3	8m	15m
4	15m	30m
5	30m	1h
6	1h	2h
7	2h	4h
8	4h	8h
9-28	8h	16h - 7d