# Webhooks
# Overview
Webhooks allows you to register your application endpoints and listen to events being triggered in Tratta.
After you've subscribed to a webhook, you can let your app execute code immediately after specific events occur in tratta, instead of having to make API calls periodically to check their status.
For example, you can rely on webhooks to trigger an action in your app when a debt acccount is created, or when a debt account is charged. By using webhooks subscriptions you can make fewer API calls overall, which makes sure that your apps are more efficient and update quickly.
# Anatomy of a webhook
After you subscribe 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.
For example, a customer.create
webhook 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
# Receive a webhook
After you register an endpoint, Tratta sends an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain the JSON data relevant to the event that triggered the request.
# Respond to a webhook
Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range indicates that you didn't receive the webhook. Tratta doesn't follow redirects for webhook notifications and considers them to be an error response.
# Frequency of retries
Tratta has implemented a five-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 will retry sending the webhook for 3 times
with a delay of 900 seconds
in between each attempt.
We will notify you with vai an email with an aggregation of all webhook failures with a period.
# Create 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
Webhook url of your application 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
secret required|string|min:16
Secret token that will be used to create a hash signature for each payload.
# Returns
A json with data
property that contains created webhook
object.
{
"id": "string",
"events": "array"
}
id
Uuid of the webhook.
# Update Webhook
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 url
Webhook url of your application Tratta will send events to.
events array|in:supported events
Array of supported events, you want to listen to. All of the events
your webhook listens to will be replaced with the new events
you specify here.
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
secret string|min:16
Secret token that will be used to create a hash signature for each payload.
# Returns
A json with data
property that contains created webhook
object.
{
"id": "string",
"events": "array"
}
# Get Webhook
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 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 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 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 will use secret
token to create hash signature of each payload. This signature is included in 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 of the webhook events can contain data that shouldn't be passed around in plain text. Such webhook payloads will be encrypted using AES 128 CBC (opens new window) NIST standard. As a shared secret we're using the secret
provided when creating a webhook.
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 webhooks
After you register your application's endpoint and Create Webhook you can trigger any of the Supported Events that you subscribed for. Trigger produces fake data that are send to your endpoint the same way webhook would. Since these data are not persisted and just fake, 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
Successfully dispatched events are included in dispatched
. Events that you tried to trigger, but didn't register your webhooks to listen to are included in not_dispatched
.
{
"dispatched": [
"location.create",
"customer.create",
"debt-account.create"
],
"not_dispatched": []
}