Webhooks

This page describes the subscription process and managing the Webhooks.

Webhooks offer a way to receive real-time notifications about various events within the system. These webhooks are designed to keep your application in sync with changes in applications or individual statuses without continuously polling the API for updates.

When an event occurs (such as an update to an application's status or individual an individual completing their checks), Tiller sends an HTTP POST request with detailed event data to a subscription URL - the webhook endpoint set up in your system. This mechanism ensures your application can react promptly to changes, facilitating workflows and more immediate responses.

Key functionalities enabled by webhooks include:

• Real-Time Notifications: Instantly receive updates about important events, reducing the delay in processing or acting upon these changes.

• Customised URL Pattern: Choose the URL pattern for the POST request with the ability to have dynamic references in the URL.

• Security: Provide Tiller with credentials to make an authenticated request to your webhook URL for increased security.

This real-time, event-driven approach is crucial for applications requiring immediate reaction to status changes in the verification process, ensuring that your integration remains up-to-date with the least amount of resource usage.

Subscribe

The Subscribe endpoint registers a webhook subscription for receiving real-time notifications. This endpoint is can dynamically set up a webhook URL tailored to specific applications or events.

When you subscribe using this endpoint, you have the option to specify a dynamic URL that includes references, such as an application ID. For example:

https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe/{application_reference}

The dynamic element needs to be an attribute of the application data. This dynamic URL structure allows for greater flexibility and specificity in handling webhook notifications. By using this dynamic URL, you can create highly responsive and tailored workflows that react promptly to relevant API events.

Subscribes to webhook notifications for mandate and individual notifications

post

/ext/webhooks/subscribe

Authorizations

Header parameters

Content-Typestring · default: application/jsonrequired

Acceptstring · default: application/jsonrequired

Body

client_idClient id

client_secretClient secret

grant_typeGrant type

auth_urlAuth url

return_urlReturn urlrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"return_url":"text"}'

200

200

[
  {
    "id": 1,
    "name": "text",
    "reference": "text",
    "status": {
      "id": 1,
      "status": "text"
    },
    "mandate_type": {
      "id": 1,
      "name": "text",
      "code": "text",
      "description": "text"
    },
    "archived": true,
    "individuals": [
      {
        "id": 1,
        "email": "[e-mail]",
        "title": "text",
        "first_name": "text",
        "middle_name": "text",
        "last_name": "text",
        "date_of_birth": "2025-02-23",
        "reference": "text",
        "status": {
          "id": 1,
          "status": "text"
        },
        "gender": "male"
      }
    ]
  }
]

Retrieve Webhook

The Retrieve Webhook endpoint serves as a tool for querying the expected webhook request data of an existing application. This endpoint can help with understanding and querying the expected response from the webhook for a particular application.

Retrieves webhook response details for a given application ID.

get

/ext/webhooks/retrieve/{application_id}

Authorizations

Path parameters

application_idstringrequired

Header parameters

Content-Typestring · default: application/jsonrequired

Acceptstring · default: application/jsonrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.tiller-verify.com/api/v1/ext/webhooks/retrieve/{application_id}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

200

200

{
  "id": 1,
  "name": "text",
  "reference": "text",
  "status": {
    "id": 1,
    "status": "text"
  },
  "mandate_type": {
    "id": 1,
    "name": "text",
    "code": "text",
    "description": "text"
  },
  "individuals": [
    {
      "id": 1,
      "mandate": 1,
      "email": "[e-mail]",
      "title": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "date_of_birth": "2025-02-23",
      "reference": "text",
      "status": {
        "id": 1,
        "status": "text"
      },
      "terms_accepted": true,
      "address": "text",
      "gender": "male"
    }
  ]
}