---
title: "Create webhook"
method: POST
path: "/v2/webhooks"
tags: ["Webhooks/Webhooks"]
---

# Create webhook

`POST /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

- WebhookCreate
  - `isAdHoc` boolean, nullable
  - `eventTypes` WebhookEventType[], required
  - `condition` WebhookCondition, required
    - `actorId` string, nullable
    - `actorTaskId` string, nullable
    - `actorRunId` string, nullable
  - `idempotencyKey` string, nullable
  - `ignoreSslErrors` boolean, nullable
  - `doNotRetry` boolean, nullable
  - `requestUrl` string, required
  - `payloadTemplate` string, nullable
  - `headersTemplate` string, nullable
  - `description` string, nullable
  - `shouldInterpolateStrings` boolean, nullable

## Response `201`

- WebhookResponse — Response containing webhook data.
  - `data` Webhook, required
    - `id` string, required
    - `createdAt` string, date-time, required
    - `modifiedAt` string, date-time, required
    - `userId` string, required
    - `isAdHoc` boolean, nullable
    - `shouldInterpolateStrings` boolean, nullable
    - `eventTypes` WebhookEventType[], required
    - `condition` WebhookCondition, required
      - `actorId` string, nullable
      - `actorTaskId` string, nullable
      - `actorRunId` string, nullable
    - `ignoreSslErrors` boolean, required
    - `doNotRetry` boolean, nullable
    - `requestUrl` string, uri, nullable — URL of the HTTP request sent by the webhook. It is omitted or `null` for hook actions other than the conventional HTTP case (e.g. Slack or email notifications).
    - `payloadTemplate` string, nullable
    - `headersTemplate` string, nullable
    - `description` string, nullable
    - `lastDispatch` ExampleWebhookDispatch
      - `status` 'ACTIVE' | 'SUCCEEDED' | 'FAILED', required — Status of the webhook dispatch indicating whether the HTTP request was successful.
      - `finishedAt` string, date-time, nullable
      - `removedAt` string, date-time, nullable
    - `stats` WebhookStats
      - `totalDispatches` integer

## Other responses

- `400` — Bad request - invalid input parameters or request body.
- `401` — Unauthorized - authentication required or invalid token.
- `403` — Forbidden - insufficient permissions to perform this action.
- `404` — Not found - the requested resource does not exist.
- `405` — Method not allowed.
- `413` — Payload too large - the request body exceeds the size limit.
- `415` — Unsupported media type - the Content-Encoding of the request is not supported.
- `429` — Too many requests - rate limit exceeded.

---

[API](https://skmtc.net/apify/apis/apify-api.md) · [All operations](https://skmtc.net/apify/apis/apify-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/apify/apify-api/versions/01a71794279b/schema)