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

POSThttps://api.tiller-verify.com/api/v1/ext/webhooks/subscribe

Authorization

Bearer

Header parameters

Body

application/json

client_idClient id

client_secretClient secret

grant_typeGrant type

auth_urlAuth url

return_url*Return url

Response

200

Body

application/json

idID

name*Name

reference*Reference

statusextapplications_status (object)

mandate_type*Mandate_type (object)

individuals*array of extapplications_individuals (object)

archivedArchived

Request

JavaScriptCurlPython

const response = await fetch('https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    body: JSON.stringify({
      "return_url": "text"
    }),
});
const data = await response.json();

Response

200

[
  {
    "id": 0,
    "name": "text",
    "reference": "text",
    "status": {
      "id": 0,
      "status": "text"
    },
    "mandate_type": {
      "id": 0,
      "name": "text",
      "code": "text",
      "description": "text"
    },
    "individuals": [
      {
        "id": 0,
        "email": "[e-mail]",
        "title": "text",
        "first_name": "text",
        "middle_name": "text",
        "last_name": "text",
        "date_of_birth": "2024-12-21",
        "gender": "male",
        "reference": "text",
        "status": {
          "id": 0,
          "status": "text"
        }
      }
    ],
    "archived": false
  }
]

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.

GEThttps://api.tiller-verify.com/api/v1/ext/webhooks/retrieve/{application_id}

Authorization

Bearer

Path parameters

application_id*string

Header parameters

Response

200

Body

application/json

idID

name*Name

referenceReference

statusextapplications_status (object)

mandate_type*inline_response_200_4_mandate_type (object)

individuals*array of inline_response_200_4_individuals (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.tiller-verify.com/api/v1/ext/webhooks/retrieve/{application_id}', {
    method: 'GET',
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
});
const data = await response.json();

Response

200

{
  "id": 0,
  "name": "text",
  "reference": "text",
  "status": {
    "id": 0,
    "status": "text"
  },
  "mandate_type": {
    "id": 0,
    "name": "text",
    "code": "text",
    "description": "text"
  },
  "individuals": [
    {
      "id": 0,
      "mandate": 0,
      "email": "[e-mail]",
      "title": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "date_of_birth": "2024-12-21",
      "gender": "male",
      "reference": "text",
      "status": {
        "id": 0,
        "status": "text"
      },
      "terms_accepted": false,
      "address": "text"
    }
  ]
}