Tratta Docs

# 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": []
}

← Customer Sessions →