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 can be dynamically set with 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.

post

Subscribes to webhook notifications for mandate and individual notifications

Authorizations

Header parameters

Content-TypestringRequiredDefault: application/json

AcceptstringRequiredDefault: application/json

Body

client_idstring | nullableOptional

client_secretstring | nullableOptional

grant_typestring | nullableOptional

auth_urlstring | nullableOptional

return_urlstringRequired

Responses

200Success

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/ext/webhooks/subscribe HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: application/json
Content-Length: 101

{
  "client_id": "text",
  "client_secret": "text",
  "grant_type": "text",
  "auth_url": "text",
  "return_url": "text"
}

200Success

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

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.

get

Retrieves webhook response details for a given application ID.

Authorizations

Path parameters

application_idstringRequired

Header parameters

Content-TypestringRequiredDefault: application/json

AcceptstringRequiredDefault: application/json

Responses

200Success

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/ext/webhooks/retrieve/{application_id} HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

200Success

{
  "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-05-16",
      "gender": "male",
      "reference": "text",
      "status": {
        "id": 1,
        "status": "text"
      },
      "terms_accepted": true,
      "address": "text"
    }
  ]
}