Skip to main content

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

Query Parameters

    limit string
    offset string
    desc string

Bodyrequired

  • 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 ..."}
  • title string | null nullable
    Example: Actor run succeeded webhook
  • 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 ...\"}",
    "title": "Actor run succeeded webhook",
    "description": "this is webhook description",
    "lastDispatch": {
      "status": "ACTIVE",
      "finishedAt": "2019-12-13T08:36:13.202Z"
    },
    "stats": {
      "totalDispatches": 1
    }
  }
}