Webhooks

Webhooks notify a listening server that a Tilia services event has occurred. Tilia services provides webhook event notifications for the following events.

Event	API operation or condition that triggers event
Account blocked / unblocked	Block account capability Unblock account capability
Balance transfer completed	Balance transfer
Deposit completed	After the facilitator wallet has received a new deposit
Escrow transaction update	Pay an escrow transaction Cancel an escrow transaction Commit an escrow transaction
Invoice completed	Balance transfer Commit an escrow transaction Pay an escrow transaction Pay an invoice Refund a line item from an invoice Refund an invoice
KYB status change	After the entity's KYB status changes
KYC state changed	After a user updates their KYC information
Payment method updated	After a payment method is added or deactivated Update payment method
Payout complete	After a payout completes successfully
Refund completed	Refund a line item from an invoice Refund an invoice
Register account completed	Register account
Token Exchange Webhook	Execute token conversion
Wallet Balance Alerts	After a publisher's wallet balance drops below their preset thresholds

Register a new webhook handler

NOTE

You must have access to Tilia Tools to register your webhook.

Repeat the following registration process for each event that you want to process.

Your webhook handler can process more than one event, if that's how you've designed it to work. However, if your webhook handler can process more than one event, you must repeat the following process for each event that you want it to process.

To register a new webhook, in Tilia Tools:

Login to Tilia Tools, and then, in the left nav, choose Webhooks .
In Webhooks , choose the Destinations tab.
In Event Destinations , choose New Event Destination .

In the Add Event Destination form, enter the details about your webhook destination:

Form field	Value to choose or enter
Webhook Version	`v1`
Event	The webhook notification that your webhook handler will process.
Destination Name	A name that identifies the endpoint. This value appears as the Name in the list of webhook handlers in Tilia Tools.
Endpoint URL	The complete URL of your webhook handler's URL. For example: `https://myhandler.example.com`.
Verify SSL	The option that describes how your webhook handler handles SSL.
Retry Policy	The option that describes how you want Tilia to retry event notifications that fail.
Authentication Type	The option that describes the authentication used by your webhook handler. `Passthrough` is no authentication.
Failure Notification Email	A valid email that can receive messages when there's a problem accessing your webhook handler.

Choose Save Event Destination to register the new webhook handler.

Develop a webhook event handler

Webhook event notifications are delivered by sending HTTPS POST requests to the URL that you provide when you register the webhook handler. You must provide the event message handler at the URL to process the message.

You can use one URL for all webhook events, one URL for each webhook event, or one URL for some and unique URLs for others. The URL-to-event-handler relationship is mapped when you register your webhook handler.

Webhook event requests contain details about the event that triggered the request. Your webhook handler can use the event details in the request body to update information on your servers.

Event message handler specification

The event handler you provide to process the webhook event messages must support the following interface:

HTTP REQUEST

The handler must accept HTTP requests that use the POST HTTP method.

POST body

The request body of a webhook event message is a JSON document similar to the following.

Copy

Copied

{
    "event_name": "event-name",
    "bucket_key": "string",
    "sent_at": "2024-02-28T17:56:21.714473539Z",
    "message": {
        ...
    }
}

Property	Description
`event_name`	The event that triggered the webhook message. The possible values for this property are listed in the Event name column of the table at the beginning of this topic.
`bucket_key`	The environment from which the request was made.
`sent_at`	The time that the webhook message was sent in GMT
`message`	The event-specific message object with information about the event that triggered the message. The details of this property are found in the webhook event reference documentation linked from the table at the beginning of this topic.

If you want one event handler to process multiple events, the handler can use the event_name property to determine how to process each event notification.

HTTP Status

Your webhook event handler should return a valid HTTP status to indicate how, or if, the notification request was handled. Returning an HTTP status of 400 or higher from your webhook event handler triggers the notification retry process.