Using webhooks

Custom webhooks are called at the end of a agent’s execution, it 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 to get notifications

Payload description:

Name

Type

Description

agentId

string

The agent ID

agentName

string

The name of the agent

script

string

The slug of the script

scriptOrg

string

The slug of the script org

branch

string

branch name

launchDuration

number

launch duration in milliseconds

runDuration

number

run duration in milliseconds

exitCode

number

exit code of the script

exitMessage

"finished"
|
"killed"
|
"global timeout"
|
"org timeout"
|
"agent timeout"
|
"unknown"

The reason why the agent ended

resultObject

string

The agent's result object

Configuration

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

And change 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 it will not be followed and be handled as an error response

Example of a successful Phantom webhook payload:

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

Webhook errors

For some reasons sending data to your webhook may fail. In these cases the orgs 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. It means that the error encountered was probably due a misconfiguration from your side. In this case details of the error will be provided.

Example of a failed Phantom webhook payload:

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