# Webhooks

**Webhooks** represent automated notifications dispatched by applications in response to specific events. These notifications consist of a message or ***payload*** in JSON format and are directed to a distinct URL. In Directual, you have the capability to generate these unique URLs for receiving such notifications.

### Creating webhooks

Go to **API** section → **Webhooks** → **+ New webhook** and enter system name of a new webhook.  In 99% of cases you will need a scenario for parsing incoming objects. Such a scenario can be created automatically right here.

![](https://3071851461-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4Nnmtk9_gFGWOddsf6%2F-MYexaauutsoulfvM97i%2F-MYf2I2AkdZd-DCUXRpp%2Fnew_hooks.gif?alt=media\&token=fced96ba-b119-4eba-a171-5b7f00e9ca17)

Copy the Webhook URL and use it with your external service to send messages to Directual.

### Storing incoming messages

After setting up a webhook, Directual automatically generates the corresponding [data structure](https://readme.directual.com/data/data-structures) within the ***Integrations*** → ***Webhooks*** folder, and you'll also find a convenient link to it in the webhooks table. The first object in this folder is created by Directual for testing purposes.

![](https://3071851461-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4Nnmtk9_gFGWOddsf6%2F-MYexaauutsoulfvM97i%2F-MYf4SfXOndQFrMTo-ZY%2Fnew_ds.gif?alt=media\&token=85ee37d4-152c-496f-927d-759519ebc884)

There are the following fields in the webhook data structure:

* `id` — usual unique field
* `body, headers, urlData` — fields in JSON format. One or a few of them contain data (depending on a specific third party service)

### Dealing with incoming messages

Objects coming via Webhooks contain data in JSON-format. The best way to deal with them is to [apply JSON-step](https://readme.directual.com/scenarios/editing-scenarios/action-steps/json-step) or to apply [templating techniques for parsing JSON](https://readme.directual.com/template-system/basics-of-template-system/advanced-templating-techniques#handling-json).

### Changing API-response

The default response is:

```
{
  "result": null,
  "status": "OK"
}
```

Occasionally, a third-party system may necessitate a specific response in JSON or even XML format. Fortunately, this is not a limitation, as you have the flexibility to construct any API response you require. Here's how:

#### 1. Add a synchronous scenario for your webhook

![](https://3071851461-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4Nnmtk9_gFGWOddsf6%2F-MYf5k4_cModS3jMoSp3%2F-MYf86iyYxMVdC0F8qSn%2Fsynch.gif?alt=media\&token=6c368cdd-0b1d-4a69-ba8a-f8ea5704e679)

Please take note that the scenario needs to be published and run.

<br>

#### 2. Setup an API-response step in the scenario

Have a look at the [API-response step documentation](https://readme.directual.com/scenarios/editing-scenarios/integration-steps/api-response).&#x20;

### Practical tip

Take a look at the tutorial on how to update an existing data table using incoming JSON data:

{% embed url="<https://youtu.be/qnc7sBiGkFg>" %}
уы
{% endembed %}


---

# 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://readme.directual.com/api-integrations/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.