# 🚧 Webhooks

Webhooks allows you to register your application endpoints and listen to events being triggered in Tratta.

# Create Webhook

POST https://api.tratta.io/api/v1/webhooks

curl https://api.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:

  • customer.create
  • customer.update
  • customer.delete
  • debt-account.create
  • debt-account.update
  • debt-account.delete
  • location.create
  • location.update
  • location.delete
  • charge.created

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://api.tratta.io/api/v1/webhooks/{id}

curl https://api.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:

  • customer.create
  • customer.update
  • customer.delete
  • debt-account.create
  • debt-account.update
  • debt-account.delete
  • location.create
  • location.update
  • location.delete
  • charge.created

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://api.tratta.io/api/v1/webhooks/{id}

curl https://api.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://api.tratta.io/api/v1/webhooks

curl https://api.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://api.tratta.io/api/v1/webhooks/{id}

curl https://api.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()

# 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.

POST https://api.tratta.io/api/v1/webhooks/trigger

curl https://api.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": []
}