# Webhooks

# Overview

Webhooks enable you to register your application's endpoints and listen for events triggered in Tratta. By subscribing to a webhook, your app can execute code immediately after specific events occur in Tratta, reducing the need for periodic API calls to check their status.

For instance, you can utilize webhooks to initiate an action in your app when a debt account is created or charged. Employing webhook subscriptions allows for fewer overall API calls, ensuring that your apps are more efficient and up-to-date.

# Webhook Anatomy

Upon subscribing to a webhook event, Tratta sends a webhook notification each time an event for that topic occurs. This notification contains a JSON payload and HTTP headers that provide context.

A customer.create webhook, for example, includes the following headers:

X-Tratta-Event-Name = customer.create
X-Tratta-Webhook-ID = xxxx is used to identify unique webhooks,
X-Tratta-Signature-256 = xxxx is used to verify webhooks

# Receiving a Webhook

Tratta sends an HTTP POST request to the specified URL each time the registered event occurs. The request's POST parameters contain the JSON data relevant to the event that triggered the request.

# Responding to a Webhook

Your webhook acknowledges data receipt by sending response with 2XX status code. Any response outside of the 2XX range indicates that you didn't receive the webhook. Tratta doesn't follow redirects for webhook notifications and considers them to be error responses.

# Retry Frequency

Tratta has implemented a 10 second timeout period and a retry period for webhook subscriptions. Tratta waits five seconds for a response to each request to a webhook. If there's no response, or an error is returned, Tratta retries sending the webhook three times with a 900-second delay between each attempt.

# Creating a Webhook

POST https://<org-uuid>.production.tratta.io/api/v1/webhooks

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d url="webhook-url" \
 -d "events[]=event-name"

# Parameters

url required|url

URL of your application's webhook that Tratta will send events to.

events required|array|in:supported events

Array of supported events you want to listen to.

Supported events:

charge.succeeded
charge.failed
customer.create
customer.update
customer.delete
debt-account.create
debt-account.update
debt-account.delete
location.create
location.update
location.delete
payment-plan.create
payment-plan.update
payment-plan.delete
external-charge.create
scheduled-charge.create
scheduled-charge.update
scheduled-charge.delete
transaction.returned-ach
transaction.settled-ach
import.complete

secret required|string|min:16

A secret token (min. 16 characters) used to create a hash signature for each payload.

# Returns

A json with data property that contains created webhook object.

{
  "id": "string",
  "events": "array"
}

UUID of the webhook.

# Update Webhook

Update a webhook's configuration by sending a PUT request to the following endpoint:

PUT https://<org-uuid>.production.tratta.io/api/v1/webhooks/{id}

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks/{id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d url="webhook-url" \
 -d "events[]=event-name"
 -X PUT

# Parameters

url required|url

The URL to which Tratta will send events.

events array|in:supported events

The list of supported events you want to subscribe to. Existing events will be replaced with the new list provided.

Supported events:

charge.succeeded
charge.failed
customer.create
customer.update
customer.delete
debt-account.create
debt-account.update
debt-account.delete
location.create
location.update
location.delete
payment-plan.create
payment-plan.update
payment-plan.delete
external-charge.create
scheduled-charge.create
scheduled-charge.update
scheduled-charge.delete
transaction.returned-ach
transaction.settled-ach
import.complete

secret required|string|min:16

A secret token used for creating a hash signature for each payload.

# Returns

A json with data property that contains created webhook object.

{
  "id": "string",
  "events": "array"
}

# Get Webhook

Get a webhook's information by sending a GET request to the following endpoint:

GET https://<org-uuid>.production.tratta.io/api/v1/webhooks/{id}

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks/{id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Returns

A json with data property that contains created webhook object.

{
  "id": "string",
  "events": "array"
}

id string

UUID of the webhook event.

events array

Array of events your webhook listens to.

# List Webhooks

Get a list of all webhooks by sending a GET request to the following endpoint:

GET https://<org-uuid>.production.tratta.io/api/v1/webhooks

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks/ \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Returns

A JSON object containing the updated webhook information:

A json with data property that contains array of webhook objects.

{
  "id": "string",
  "events": "array"
}

id string

UUID of the webhook.

events array

Array of events your webhook listens to.

# Delete Webhook

Delete a webhook by sending a DELETE request to the following endpoint:

DELETE https://<org-uuid>.production.tratta.io/api/v1/webhooks/{id}

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -X DELETE

# Returns

{
  "success": "boolean"
}

# Securing Webhooks

Tratta uses the provided secret token to create a hash signature for each payload. This signature is included in the header of each webhook request as X-Tratta-Signature-256.

# Pseudo code
secret = secret provided when creating webhook
payload = string of post body payload of request
signature = hmac_hex_digest('sha256', secret, payload)

Python

import hmac
import hashlib

secret = "123412341234123412341234"

payload = '{"data":{"id":"ccd912ca-134b-4743-9ab8-1561d6143caa",
"name":"Test customer","email":"test@email.com","phone":null,"external_id":null}}'

secret = bytes(secret, 'UTF-8')
payload = bytes(payload, 'UTF-8')

h = hmac.new(secret, payload, hashlib.sha256)

signature = h.hexdigest()

# Encrypting Payload

Some webhook events may contain sensitive data that should not be transmitted in plain text. In these cases, webhook payloads will be encrypted using the AES 128 CBC (opens new window)CBC NIST standard. The secret provided when [creating a webhook (/webhooks.html#create-webhook) serves as the shared secret.

Events with encrypted payloads:

external-charge.create

Webhook payload is encrypted with implementation compatible with https://github.com/tasos-py/AES-Encryption-Classes (opens new window).

# Testing Multiple Webhooks

After registering your application's endpoint and creating a webhook, you can trigger any of the Supported Events you've subscribed to. The trigger generates fake data that is sent to your endpoint in the same manner as a webhook. Since this data is not persisted and is only for testing purposes, id properties will be replaced with null.

POST https://<org-uuid>.production.tratta.io/api/v1/webhooks/trigger

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks/trigger \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d "events[]=customer.create" \
 -d "events[]=customer.update"

# Returns

The response includes successfully dispatched events in the dispatched array. Events you attempted to trigger but did not register your webhook to listen to are included in the not_dispatched array.

{
    "dispatched": {
        "https://weebhook-url": [
              "location.create",
              "customer.create",
              "debt-account.create"
        ]
    },
    "not_dispatched": []
}

# Testing Single Webhooks

POST https://<org-uuid>.production.tratta.io/api/v1/webhooks/trigger/:webhook-uuid

curl https://<org-uuid>.production.tratta.io/api/v1/webhooks/trigger/:webhook-uuid \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d "events[]=customer.create" \
 -d "events[]=customer.update"

← Payment Methods Customer Sessions →