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:
Name | Type | Description |
---|---|---|
agentId | string | The agent ID |
agentName | string | The name of the agent |
containerId | string | The container ID |
script | string | The slug of the script |
scriptOrg | string | The slug of the script org |
branch | string | The branch name |
launchDuration | number | launch duration in milliseconds |
runDuration | number | run duration in milliseconds |
exitCode | number | exit code of the script |
exitMessage | "finished" | 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.
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.
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
}
Updated about 1 month ago