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

{% openapi src="/files/d3yB4cFl16j0xlR4QP71" path="/ext/webhooks/subscribe" method="post" %}
[TillerTechnologies-verify-api-v1-oas3.json](https://content.gitbook.com/content/0zS5rWXn6QhdPJuSHu9k/blobs/QIqANJoV2sVgHqFFWsfb/TillerTechnologies-verify-api-v1-oas3.json)
{% endopenapi %}

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

{% openapi src="/files/d3yB4cFl16j0xlR4QP71" path="/ext/webhooks/retrieve/{application\_id}" method="get" %}
[TillerTechnologies-verify-api-v1-oas3.json](https://content.gitbook.com/content/0zS5rWXn6QhdPJuSHu9k/blobs/QIqANJoV2sVgHqFFWsfb/TillerTechnologies-verify-api-v1-oas3.json)
{% endopenapi %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://verify-doc.tiller-verify.com/verify-api/endpoints/api-reference/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.