> ## Documentation Index > Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Listen for events within the Tesouro system and get notified of any changes in your data. ## Overview Webhooks allow partners to subscribe to real-time notifications of specific events occurring within the Tesouro system. Tesouro sends these events via HTTPS as a JSON payload to an endpoint set by you. You can then use these notifications to execute actions in your backend systems. ## How to subscribe to webhooks To start receiving webhooks, follow these steps: 1. Identify the [events](#events) you want to monitor. 2. Create the webhook listener endpoint on your server. 3. Subscribe to the desired events by calling [`POST /webhook-subscriptions`](/finops/reference/openapi/webhook-subscriptions/post-webhook-subscriptions). 4. Handle the requests from Tesouro. ### 1. Identify the events you want to monitor Currently, Tesouro triggers notifications for the following objects and events: | Object | Events | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `accounting_connection` | `connected`, `disconnected`, `deauthorized`, `pending_auth` | | `approval_policy` | `created`, `deleted`, `process_canceled`, `updated` | | `approval_policy_process` | `created`, `execution_error` | | `approval_request` | `approved`, `canceled`, `created`, `rejected` | | `batch_payment` | `status_updated` | | `comment` | `create`, `update` | | `counterpart` | `created`, `delete`, `metadata_update`, `updated` | | `counterpart_address` | `created`, `delete`, `update` | | `counterpart_bank_account` | `created`, `delete`, `update` | | `counterpart_contact_person` | `created`, `delete`, `make_default`, `update` | | `counterpart_tax_id` | `created`, `delete`, `update` | | `counterpart_vat_id` | `created`, `delete`, `update` | | `delivery_note` | `created`, `updated`, `delivered`, `canceled`, `deleted` | | `entity` | `created`
`onboarding_requirements.status_updated`
`onboarding_requirements.updated`
`payment_method.us_ach.activated`
`payment_method.us_ach.deactivated`
`updated` | | `ocr_task` | `finished` | | `payable` | `approved`
`canceled`
`created_from_mail`
`created`
`deleted`
`multiple_approval_policies_matched`
`rejected`
`ocr_finished`
`paid`
`partially_paid`
`reopened`
`submitted_for_approval`
`updated` | | `payable_line_item` | `created`, `deleted`, `updated` | | `payment_intent` | `status_updated` | | `payment_link` | `created`, `status_updated` | | `project` | `created`, `deleted`, `updated` | | `receipt` | `created`, `deleted`, `updated`, `ocr_finished` | | `receivable` |

**Common events**

`created` - Triggered when a new invoice, quote, or credit note is created. This includes invoices created on a [recurring schedule](/finops/guides/accounts-receivable/invoices/recurring).

`updated` - Triggered when a receivable is updated via `PATCH /receivables/{receivable_id}`. Note that this does not include line item updates for invoices and quotes.

`deleted` - Triggered when a draft receivable is deleted.

`issuing` - Triggered when an invoice or credit note is submitted to an [e-invoicing](/finops/guides/e-invoicing/send) network.

`issued` - Triggered when a receivable becomes issued.

`failed` - Triggered when:

**Invoice-specific events**

`canceled` - Triggered when an invoice is [canceled](/finops/guides/accounts-receivable/invoices/manage#cancel) (whether directly or via a credit note).

`overdue` - Triggered when an invoice becomes [overdue](/finops/guides/accounts-receivable/invoices/index#overdue).

`paid` - Triggered when an invoice's status becomes [`paid`](/finops/guides/accounts-receivable/invoices/index#paid).

`partially_paid` - Triggered when an invoice's status becomes [`partially_paid`](/finops/guides/accounts-receivable/invoices/index#partially-paid).

`uncollectible` - Triggered when an invoice is marked as [uncollectible](/finops/guides/accounts-receivable/invoices/manage#mark-as-uncollectible).

**Quote-specific events**

`accepted` - triggered when a quote is [accepted](/finops/guides/accounts-receivable/quotes/manage#accept-or-decline).

`declined` - triggered when a quote is declined.

`expired` - triggered when a quote [expires](/finops/guides/accounts-receivable/quotes/manage#expiration).

| | `tag` | `created`, `deleted`, `updated` | | `transaction` | `created`, `deleted`, `updated` | ### 2. Create a webhook listener endpoint on your server To receive webhooks requests from Tesouro, you must set up an HTTPS endpoint on your server. You can use one endpoint to handle several different event types at once or set up individual endpoints for specific events. If you want to receive webhooks from both production and sandbox [environments](/finops/api/concepts/environments), we recommend that you use separate webhoook listener endpoints for these environments. Your webhook listener endpoint must be accessible from the public Internet, accept POST requests, and respond with HTTP status code 200 to acknowledge successful receipt of the webhook. Tesouro webhooks do not follow redirects, so make sure to specify a direct URL when subscribing to webhooks. You can expect a JSON request body with the following structure: ```json lines theme={null} { "id": "90cc1b23-9681-40f4-a54b-4c059cd4397d", "created_at": "2024-03-04T20:08:48.399442+00:00", "action": "entity.onboarding_requirements.updated", "api_version": "2025-06-23", "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0", "description": "entity_onboarding_requirements_updated", "object": { "id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0" }, "object_type": "entity", "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187" } ``` The possible values for `action` are listed in the [table above](#events). ### 3. Subscribe to webhooks To subscribe to the desired Tesouro webhook events, call [`POST /webhook-subscriptions`](/finops/reference/openapi/webhook-subscriptions/post-webhook-subscriptions) with the request body containing your webhook listener `url` and the events you want to be notified about. If you omit `event_types`, Tesouro will notify you about all events of the specified `object_type`. ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/webhook-subscriptions' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://example.com/your-webhook-listener", "object_type": "entity", "event_types": [ "created", "updated" ] }' ``` The successful response contains the `id` assigned to this webhook subscription and the `secret` that you can use to [verify webhook signatures](/finops/guides/getting-started/webhooks/signatures): ```json lines theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", ... "secret": "whsec_Iw3mr...", "status": "enabled", "url": "https://example.com/your-webhook-listener" } ``` ### 4. Handle the requests from Tesouro To handle the events sent by Tesouro, parse the body of the requests that arrive at your webhook endpoint. You can use the `entity_id`, `object_type`, and `object_id` fields to identify the affected organization and the object that was changed. For example, the following webhook event means that an organization with ID `3fa85f64-5717-4562-b3fc-2c963f66afa6` created a new counterpart and that counterpart was assigned ID `f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe`: ```json lines theme={null} { "id": "06c003f1-6b05-415f-be6d-39ecacdddbd3", "created_at": "2024-03-04T20:06:48.593225+00:00", "action": "counterpart.created", "api_version": "2025-06-23", "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "counterpart has been created", "object": { "id": "f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe" }, "object_type": "counterpart", "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187" } ``` To get the full details of the created counterpart, you can then call [`GET /counterparts/f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe`](/finops/reference/openapi/counterparts/get-counterparts-id). ## Retry policy If your webhook listener endpoint returns any HTTP status code other than 200 - for example, 204 or 301 - Tesouro considers the webhook delivery unsuccessful. We automatically retry sending the webhook for a total of a week. The time interval between the retries follows this schedule: * 2 minutes * 5 minutes * 10 minutes * 15 minutes * 30 minutes * 1 hour * 2 hours * 4 hours * 8 hours * After that, the webhook will be retried every 8 hours If the unavailability persists for a total of a week, Tesouro automatically disables the corresponding webhook subscription and all further requests are canceled, including for new events. Additionally, Tesouro sends an email notification to the partner's email address informing them of the disabled webhook subscription and providing details for further action. After resolving the issues with the webhook listener endpoint, the partner can manually [re-enable](#enable) the affected webhook subscription. Partners can use [`GET /events`](/finops/reference/openapi/events/get-events) to get the missed webhook events from the period when their webhook listener was unavailable: ```lines theme={null} GET /events?created_at__gte=&created_at__lte= ``` Tesouro uses an "at least once" delivery policy for all webhook events. This means that: * Events may occasionally be delivered more than once. * Retries can occur if your endpoint fails to acknowledge receipt (e.g., non-200 response or timeout). * When retried, the event will include the same unique `id` as the original delivery. Because of this, event deduplication is required on the customer's side. You should use the `id` to identify and ignore duplicates. ## Review webhook deliveries Tesouro keeps a log of delivery attempts for all webhook events that partners are subscribed to. A partner can call [`GET /webhook-deliveries`](/finops/reference/openapi/webhook-deliveries/get-webhook-deliveries) to access the webhook delivery log for the events of a specific organization: ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/webhook-deliveries' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` The response contains information about how many times an event was triggered, the event ID, the status code of the last attempt, and whether or not the final attempt was successful. Available data is limited to the last three months. ## List all webhook subscriptions To get a list of your existing webhook subscriptions, call [`GET /webhook-subscriptions`](/finops/reference/openapi/webhook-subscriptions/get-webhook-subscriptions). You can optionally filter the list by the webhook event type and the subscription date. For example: * Get all subscriptions for `entity` events: ```lines theme={null} GET /webhook-subscriptions?object_type=entity ``` * Get all subscriptions created on or after September 1, 2024: ```lines theme={null} GET /webhook-subscriptions?created_at__gte=2024-09-01T00:00:00Z ``` ## Retrieve a webhook subscription To get the details of a specific webhook subscription, call [`GET /webhook-subscriptions/{webhook_subscription_id}`](/finops/reference/openapi/webhook-subscriptions/get-webhook-subscriptions-id). ## Update a webhook subscription To update an existing webhook subscription, call [`PATCH /webhook-subscriptions/{webhook_subscription_id}`](/finops/reference/openapi/webhook-subscriptions/patch-webhook-subscriptions-id). You can update the webhook listener URL and the list of events to get notifications for. ## Disable a webhook subscription All webhook subscriptions are enabled by default but get automatically disabled if Tesouro cannot connect to the webhook listener URL after [a series of retries](#retry-policy). You can also disable a webhook subscription manually by calling [`POST /webhook-subscriptions/{webhook_subcription_id}/disable`](/finops/reference/openapi/webhook-subscriptions/post-webhook-subscriptions-id-disable): ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/webhook-subscriptions/c7f37...187/disable' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` While a webhook subscription is disabled, the associated events are not triggered and therefore are not included in historical webhook data available via `GET /events` and `GET /webhook-deliveries`. ## Enable a webhook subscription To re-enable a disabled webhook subscription, call [`POST /webhook-subscriptions/{webhook_subscription_id}/enable`](/finops/reference/openapi/webhook-subscriptions/post-webhook-subscriptions-id-enable): ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/webhook-subscriptions/c7f37...187/enable' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## Delete a webhook subscription To delete a webhook subscription, call [`DELETE /webhook-subscriptions/{webhook_subscription_id}`](/finops/reference/openapi/webhook-subscriptions/delete-webhook-subscriptions-id). You will stop receiving webhooks for the events listed in that subscription.