# Webhooks

Webhooks, also called a web callback or HTTP push API, are the API concepts that are getting more and more popular. Thanks to their lightweight and speed they provide data between applications immediately. With webhooks, you can pass and retrieve information from a matched interaction to your web service.

## List all Webhooks

Returns list of all created webhooks.

GET https://api.chatbot.com/webhooks

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `id` | String | Webhook id. |
| `name` | String | Webhook name. |
| `url` | String | Webhook public url. |
| `error` | String | Last noted error with your webhook. |

#### Request URL

```
curl --request GET \
\t--url https://api.chatbot.com/webhooks \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
```

#### Response Example

```
[
    {
        "id": "5a21a9e21ec94a0007f9ac19",
        "name": "Webhook",
        "url": "https://example.com",
        "error": ""
    }
]
```

## Get a specific webhook

Returns a specific webhook object.

GET https://api.chatbot.com/webhooks/:ID

#### Request URL

```
curl --request GET \
\t--url https://api.chatbot.com/webhooks/:ID \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
```

#### Response Example

```
{
    "id": "5a21a9e21ec94a0007f9ac19",
    "name": "Webhook example",
    "url": "https://example.com",
    "token": "qwerty",
    "headers": [],
    "auth": {
        "username": "",
        "password": ""
    },
    "error": {
        "date": "2017-12-04T15:06:12.053Z",
        "message": "timeout of 10000ms exceeded"
    }
}
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `id` | String | Webhook id. |
| `name` | String | Webhook name. |
| `url` | String | Webhook url. Must be public url. |
| `token` | String | Token which can be used to verify incoming webhooks. |
| [`headers`](https://www.chatbot.com/docsv1/webhooks/#headers) | Array.< [Object](https://www.chatbot.com/docsv1/webhooks/#headers) > | Array of [objects](https://www.chatbot.com/docsv1/webhooks/#headers) which includes request headers. |
| [`auth`](https://www.chatbot.com/docsv1/webhooks/#auth) | [Object](https://www.chatbot.com/docsv1/webhooks/#auth) | [Object](https://www.chatbot.com/docsv1/webhooks/#auth) for basic auth authorization. |
| `error` | Object | Error object which includes information about last occured error. |

## Create a webhook

Creates a new webhook.

```
curl --request POST \
\t--url https://api.chatbot.com/webhooks \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
\t--header 'content-type: application/json' \
\t--data '
{
    "name": "Webhook name",
    "url": "${WEBHOOK-URL}",
    "token": "",
    "headers": [],
    "auth": {}
}
'
```

#### Request URL

{
"name": "Webhook name",
"url": "${WEBHOOK-URL}",
"token": "",
"headers": [],
"auth": {}
}

#### Response Example

```
{
    "id": "58ee2e085d033800059a3f7f",
    "timestamp": "2018-01-12T13:40:40.260Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `name` | String | Webhook name. <br>`String(1, 1024)` |
| `url` | String | Webhook public url. |
| `token` | String | Token which can be used to verification incoming webhooks. <br>`String(1, 1024)` |
| [`headers`](https://www.chatbot.com/docsv1/webhooks/#headers) | Array.< [Object](https://www.chatbot.com/docsv1/webhooks/#headers) > | Array of [objects](https://www.chatbot.com/docsv1/webhooks/#headers) which includes request headers. <br>`Array(1, 99)` |
| [`auth`](https://www.chatbot.com/docsv1/webhooks/#auth) | [Object](https://www.chatbot.com/docsv1/webhooks/#auth) | [Object](https://www.chatbot.com/docsv1/webhooks/#auth) for basic auth authorization. |

## Update a webhook

Updates a webhook.

PUT https://api.chatbot.com/webhooks/:ID

#### Request URL

```
curl --request PUT \
\t--url https://api.chatbot.com/webhooks/:ID \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
\t--header 'content-type: application/json' \
\t--data '
{
    "name": "Webhook name",
    "url": "${WEBHOOK-URL}",
    "token": "",
    "headers": [],
    "auth": {}
}
'
```

#### Response Example

```
{
    "id": "58ee2e085d033800059a3f7f",
    "timestamp": "2018-01-12T13:40:40.260Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}
```

#### Properties

## Delete a webhook

Removes a webhook.

```
curl --request DELETE \
\t--url https://api.chatbot.com/webhooks/:ID \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
\t--header 'content-type: application/json'
```

#### Request URL

#### Response Example

```
{
    "id": "58ee2e085d033800059a3f7f",
    "timestamp": "2018-01-12T13:40:40.260Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}
```

## Common object definitions

#### `headers`

Array of request headers.

| Property | Type | Description |
| --- | --- | --- |
| `name` | String | Header name.<br>`String(1, 128)` |
| `value` | String | Header value.<br>`String(1, 1024)` |

#### `auth`

| Property | Type | Description |
| --- | --- | --- |
| `username` | String | Basic auth username.<br>`String(1, 1024)` |
| `password` | String | Basic auth password.<br>`String(1, 1024)` |

## Webhook integration examples

Don’t know how to setup your first ChatBot webhook? [Check it here](https://www.chatbot.com/help/webhooks/setting-up-your-webhook/) or get our ready to use examples:

- [Node.js without any libraries](https://github.com/BotEngineAI/nodejs-webhook-example)
- [Node.js using express + body-parser](https://github.com/BotEngineAI/nodejs-express-webhook-example)
- [PHP](https://github.com/BotEngineAI/php-webhook-example)
- [Firebase example](https://github.com/BotEngineAI/nodejs-firebase-webhook-example)