Using webhooks

Custom webhooks are called at the end of an agent’s execution, they will POST a payload containing some useful information about your Phantom’s status and result to its associated Webhook URL.

📘

Webhooks integration

Phantombuster provides a custom webhook integration which enables you to automate workflows between your apps and your agents, it also allows you to get notifications

Payload description:

Configuration

To set the webhook URL of your agent, go to the setup agent page and, in settings, select Advanced Notification Settings.

You can then input your webhook URL in the webhook field:

📘

Sending a secret

For security reasons, you may want to set a secret that will be sent with the request when your webhook is called.
Unfortunately webhooks don't support request headers customization but you can always pass a secret using the query params: http://example.com/webhook?secret=MY_SECRET_KEY

Receiving data

❗️

Your webhook endpoint needs to accept POST requests in order to receive the agent data. It also should not respond with more than 2 redirections since they will not be followed and will be handled as an error response

Example of a successful Phantom webhook payload:

{ 
  "agentId": "5027055349780535",
  "agentName": "Test Script",
  "containerId": "3358014727012763",
  "script": "test_script_50516785467.js",
  "scriptOrg": "phantombuster",
  "branch": "test-branch-0545107204",
  "launchDuration": 121,
  "runDuration": 1850,
  "resultObject": {...},
  "exitMessage": "finished",
  "exitCode": 0
}

Webhook errors

In some cases sending data to your webhook may fail. In these cases the org users will be informed of the failure by an email containing details of the event.

This email can, sometimes, warn that the webhook has been removed from your configuration. This means that the error encountered was probably due to a misconfiguration from your side. In this case details of the error will be provided.

We do not remove a webhook when the error is out of your control, such as a network error.
But only when we are waiting for a fix on the webhook from your side.

The errors that can unregister a webhook are:

• HTTP responses status code between 400 and 499 (client error response).
• Too many redirections (the maximum allowed is 2 redirections).
• Invalid redirection (such as invalid URL, use of credentials or use of IPv6 address).

Example of a failed Phantom webhook payload:

{ 
  "agentId": "5027055349780535",
  "agentName": "Test Script",
  "containerId": "3358014727012763",
  "script": "test_script_50516785467.js",
  "scriptOrg": "phantombuster",
  "branch": "test-branch-0545107204",
  "launchDuration": 93,
  "runDuration": 1034,
  "resultObject": null,
  "exitMessage": "finished",
  "exitCode": 1
}

Request Timeouts

Webhooks requests are subject to timeouts, limiting the duration of their execution. The maximum timeout that can be reached by a webhook is 11 seconds.
If the request exceeds this time limit, it is cancelled and considered a server error. It's important to note that timeout errors do not disable webhooks.

Of the 11 seconds allocated to a webhook timeout, 5 seconds are dedicated to opening the connection, 5 seconds to waiting for the response headers, and 1 second to reading the entire response.
It should be noted that the response body is ignored and there is no need to respond with a body.