# Create webhook


```
POST 
https://api.apify.com/v2/webhooks
```


Creates a new webhook with settings provided by the webhook object passed as JSON in the payload. The response is the created webhook object.

To avoid duplicating a webhook, use the `idempotencyKey` parameter in the request body. Multiple calls to create a webhook with the same `idempotencyKey` will only create the webhook with the first call and return the existing webhook on subsequent calls. Idempotency keys must be unique, so use a UUID or another random string with enough entropy.

To assign the new webhook to an Actor or task, the request body must contain `requestUrl`, `eventTypes`, and `condition` properties.

* `requestUrl` is the webhook's target URL, to which data is sent as a POST request with a JSON payload.
* `eventTypes` is a list of events that will trigger the webhook, e.g. when the Actor run succeeds.
* `condition` should be an object containing the ID of the Actor or task to which the webhook will be assigned.
* `payloadTemplate` is a JSON-like string, whose syntax is extended with the use of variables.
* `headersTemplate` is a JSON-like string, whose syntax is extended with the use of variables. Following values will be re-written to defaults: "host", "Content-Type", "X-Apify-Webhook", "X-Apify-Webhook-Dispatch-Id", "X-Apify-Request-Origin"
* `description` is an optional string.
* `shouldInterpolateStrings` is a boolean indicating whether to interpolate variables contained inside strings in the `payloadTemplate`


```
"isAdHoc" : false,
    "requestUrl" : "https://example.com",
    "eventTypes" : [
        "ACTOR.RUN.SUCCEEDED",
        "ACTOR.RUN.ABORTED"
    ],
    "condition" : {
        "actorId": "5sTMwDQywwsLzKRRh",
        "actorTaskId" : "W9bs9JE9v7wprjAnJ"
    },
    "payloadTemplate": "",
    "headersTemplate": "",
    "description": "my awesome webhook",
    "shouldInterpolateStrings": false,
```


**Important**: The request must specify the `Content-Type: application/json` HTTP header.

## Request

<!-- -->

### Body**required**

* **isAdHoc** boolean | null nullable\
  **Example:** `false`

* **eventTypes** WebhookEventType (string)\[] required

  **Possible values:** \[`ACTOR.BUILD.ABORTED`, `ACTOR.BUILD.CREATED`, `ACTOR.BUILD.FAILED`, `ACTOR.BUILD.SUCCEEDED`, `ACTOR.BUILD.TIMED_OUT`, `ACTOR.RUN.ABORTED`, `ACTOR.RUN.CREATED`, `ACTOR.RUN.FAILED`, `ACTOR.RUN.RESURRECTED`, `ACTOR.RUN.SUCCEEDED`, `ACTOR.RUN.TIMED_OUT`, `TEST`]

  **Example:** `["ACTOR.RUN.SUCCEEDED"]`

* **condition** object required

  * **actorId** string | null nullable\
    **Example:** `hksJZtadYvn4mBuin`
  * **actorTaskId** string | null nullable\
    **Example:** `asdLZtadYvn4mBZmm`
  * **actorRunId** string | null nullable\
    **Example:** `hgdKZtadYvn4mBpoi`

* **idempotencyKey** string | null nullable\
  **Example:** `fdSJmdP3nfs7sfk3y`

* **ignoreSslErrors** boolean | null nullable\
  **Example:** `false`

* **doNotRetry** boolean | null nullable\
  **Example:** `false`

* **requestUrl** string\<uri> required\
  **Example:** `http://example.com/`

* **payloadTemplate** string | null nullable\
  **Example:** `{\n "userId": {{userId}}...`

* **headersTemplate** string | null nullable\
  **Example:** `{\n "Authorization": "Bearer ..."}`

* **description** string | null nullable\
  **Example:** `this is webhook description`

* **shouldInterpolateStrings** boolean | null nullable\
  **Example:** `false`

### Status 201

**Response Headers**

* **Location**


```
{
  "data": {
    "id": "YiKoxjkaS9gjGTqhF",
    "createdAt": "2019-12-12T07:34:14.202Z",
    "modifiedAt": "2019-12-13T08:36:13.202Z",
    "userId": "wRsJZtadYvn4mBZmm",
    "isAdHoc": false,
    "shouldInterpolateStrings": false,
    "eventTypes": [
      "ACTOR.RUN.SUCCEEDED"
    ],
    "condition": {
      "actorId": "hksJZtadYvn4mBuin",
      "actorTaskId": "asdLZtadYvn4mBZmm",
      "actorRunId": "hgdKZtadYvn4mBpoi"
    },
    "ignoreSslErrors": false,
    "doNotRetry": false,
    "requestUrl": "http://example.com/",
    "payloadTemplate": "{\\n \"userId\": {{userId}}...",
    "headersTemplate": "{\\n \"Authorization\": \"Bearer ...\"}",
    "description": "this is webhook description",
    "lastDispatch": {
      "status": "ACTIVE",
      "finishedAt": "2019-12-13T08:36:13.202Z"
    },
    "stats": {
      "totalDispatches": 1
    }
  }
}
```


**Schema**

* **data** object required

  * **id** string required\
    **Example:** `YiKoxjkaS9gjGTqhF`

  * **createdAt** string\<date-time> required\
    **Example:** `2019-12-12T07:34:14.202Z`

  * **modifiedAt** string\<date-time> required\
    **Example:** `2019-12-13T08:36:13.202Z`

  * **userId** string required\
    **Example:** `wRsJZtadYvn4mBZmm`

  * **isAdHoc** boolean | null nullable\
    **Example:** `false`

  * **shouldInterpolateStrings** boolean | null nullable\
    **Example:** `false`

  * **eventTypes** WebhookEventType (string)\[] required

    **Possible values:** \[`ACTOR.BUILD.ABORTED`, `ACTOR.BUILD.CREATED`, `ACTOR.BUILD.FAILED`, `ACTOR.BUILD.SUCCEEDED`, `ACTOR.BUILD.TIMED_OUT`, `ACTOR.RUN.ABORTED`, `ACTOR.RUN.CREATED`, `ACTOR.RUN.FAILED`, `ACTOR.RUN.RESURRECTED`, `ACTOR.RUN.SUCCEEDED`, `ACTOR.RUN.TIMED_OUT`, `TEST`]

    **Example:** `["ACTOR.RUN.SUCCEEDED"]`

  * **condition** object required

    * **actorId** string | null nullable\
      **Example:** `hksJZtadYvn4mBuin`
    * **actorTaskId** string | null nullable\
      **Example:** `asdLZtadYvn4mBZmm`
    * **actorRunId** string | null nullable\
      **Example:** `hgdKZtadYvn4mBpoi`

  * **ignoreSslErrors** boolean required\
    **Example:** `false`

  * **doNotRetry** boolean | null nullable\
    **Example:** `false`

  * **requestUrl** string\<uri> required\
    **Example:** `http://example.com/`

  * **payloadTemplate** string | null nullable\
    **Example:** `{\n "userId": {{userId}}...`

  * **headersTemplate** string | null nullable\
    **Example:** `{\n "Authorization": "Bearer ..."}`

  * **description** string | null nullable\
    **Example:** `this is webhook description`

  * **lastDispatch** object

    * anyOf

      * ExampleWebhookDispatch
      * null

      **status** WebhookDispatchStatus (string) required

      Status of the webhook dispatch indicating whether the HTTP request was successful.

      **Possible values:** \[`ACTIVE`, `SUCCEEDED`, `FAILED`]

    * **finishedAt** string,null\<date-time> nullable\
      **Example:** `2019-12-13T08:36:13.202Z`

  * **stats** object

    * anyOf
      * WebhookStats
      * null
      **totalDispatches** integer required\
      **Example:** `1`

### Status 400

Bad request - invalid input parameters or request body.


```
{
  "error": {
    "type": "invalid-input",
    "message": "Invalid input: The request body contains invalid data."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 401

Unauthorized - authentication required or invalid token.


```
{
  "error": {
    "type": "token-not-valid",
    "message": "Authentication token is not valid."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 403

Forbidden - insufficient permissions to perform this action.


```
{
  "error": {
    "type": "permission-denied",
    "message": "You do not have permission to perform this action."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 405

Method not allowed.


```
{
  "error": {
    "type": "method-not-allowed",
    "message": "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET"
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 413

Payload too large - the request body exceeds the size limit.


```
{
  "error": {
    "type": "request-too-large",
    "message": "The POST payload is too large (limit: 9437184 bytes, actual length: 10485760 bytes)."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 415

Unsupported media type - the Content-Encoding of the request is not supported.


```
{
  "error": {
    "type": "unsupported-content-encoding",
    "message": "Content-Encoding \"bla\" is not supported."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 429

Too many requests - rate limit exceeded.


```
{
  "error": {
    "type": "rate-limit-exceeded",
    "message": "You have exceeded the rate limit. Please try again later."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`