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 capabilityUnblock account capability Balance transfer completed Balance transfer Deposit completed After the facilitator wallet has received a new deposit Escrow transaction update Pay an escrow transactionCancel an escrow transactionCommit an escrow transaction Invoice completed Balance transferCommit an escrow transactionPay an escrow transactionPay an invoiceRefund a line item from an invoiceRefund 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 deactivatedUpdate payment method Payout complete After a payout completes successfully Refund completed Refund a line item from an invoiceRefund 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 NOTEYou 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 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.