Webhooks

Webhooks provide an easy and reliable way to configure the Apify platform to carry out an action (e.g. a HTTP request to another service) when a certain system event occurs. For example, you can use webhooks to start another actor when an actor run finishes or fails.

The webhook is defined by the event that triggers the webhook and action that is performed on behalf of the event. When the event occurs, the systems sends a HTTP POST request to an external URL specified in the webhook.

The response to the POST request must have a HTTP status code in the 2XX range. Otherwise it is considered an error and the request is periodically retried with an exponential back-off: first retry happens after roughly 1 minute, second after 2 minutes, third after 4 minutes etc. After 11 such retries which take around 32 hours, the system gives up and stops retrying the requests.

For safety reasons, the webhook URL should contain a secret token to ensure only Apify can invoke it. To test your endpoint, you can use the Test button in the user interface. The timeout of the webhook HTTP request is 30 seconds. If your endpoint performs a time-consuming operation, you should respond to the request immediately so that it does not time out before Apify receives the response. To ensure that the time-consuming operation is reliably finished, you can internally use a message queue to retry the operation on internal failure. In rare circumstances, the webhook might be invoked more than once, you should design your code to be idempotent to duplicate calls.

Events

Webhooks are currently available for actor run events, with new types in the pipeline.

Actor run

Actor run events are triggered when an actor run gets created or transitions into a new state. Webhook can be defined for all runs of an actor at its detail page or for a specific actor task at its detail page. In that case, the webhook is performed only for runs started for that task.

  • ACTOR.RUN.CREATED - New actor run has been created.
  • ACTOR.RUN.SUCCEEDED - Actor run finished with status SUCCEEDED
  • ACTOR.RUN.FAILED - Actor run finished with status FAILED
  • ACTOR.RUN.ABORTED - Actor run finished with status ABORTED
  • ACTOR.RUN.TIMED_OUT - Actor run finished with status TIMED-OUT

Actions

Currently, the HTTP request can be performed on behalf of an event. New actions will come later.

HTTP request

This action is performed by the HTTP POST request to the provided URL with JSON payload containing info about the event and the object of the actor run:

{
    "eventType": "ACTOR.RUN.SUCCEEDED",
    "eventData": {
        "actorId": "fW4MyDhgwtMLrB987",
        "actorRunId": "uPBN9qaKd2iLs5naZ"
    },
    "resource": {
        "id": "uPBN9qaKd2iLs5naZ",
        "actId": "fW4MyDhgwtMLrB987",
        "userId": "abf6vtB2nvQZ4nJzo",
        "startedAt": "2019-01-09T15:59:40.750Z",
        "finishedAt": "2019-01-09T15:59:56.408Z",
        "status": "SUCCEEDED",
        ...
    }
}

To see the complete run object as contained under resource property check API documentation of get actor run API endpoint.

Ad hoc webhooks

An ad hoc webhook is a one-time webhook created for a certain actor run when starting the run using Apify API. It's triggered at most once when the given run transitions into the appreciated state. Ad hoc webhooks can be defined using a URL parameter webhooks added to the API endpoint that starts an actor or actor task:

https://api.apify.com/v2/acts/[ACTOR_ID]/runs?token=[YOUR_API_TOKEN]&webhooks=[AD_HOC_WEBHOOKS]

where AD_HOC_WEBHOOKS is a base64 encoded stringified JSON array of webhook definitions:

[
    {
        "eventTypes": ["ACTOR.RUN.CREATED"],
        "requestUrl": "https://example.com/run-created"
    },
    {
        "eventTypes": ["ACTOR.RUN.SUCCEEDED"],
        "requestUrl": "https://example.com/run-succeeded"
    },
]