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 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 |
You must have access to Tilia Tools to register your webhook.
Contact us if you need access to Tilia Tools.
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 v1Event 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. Passthroughis 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.
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.
The event handler you provide to process the webhook event messages must support the following interface:
The handler must accept HTTP requests that use the POST HTTP method.
The request body of a webhook event message is a JSON document similar to the following.
{
"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.
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.