How-To: Add & Manage Webhook Triggers

About Webhook Triggers

Webhook Triggers enable you to programmatically execute a Workflow in Platform by running a POST request from any service. When you run the POST request, your Workflow will be scheduled to run immediately. You can also use webhooks to dynamically pass data to your Vessels at runtime.

Webhook triggers differ from API triggers in the following ways:

• Webhook triggers will work without authentication for anyone that has access to the URL.

This means you should treat your webhook URL like a passcord - keep it secure, never share it unless with a trusted individual, and if it is leaked or you believe it has been compromised, refresh the webhook URL to make previous ones unusable.

• Webhooks can accept ANY data, while API triggers require a specific JSON payload.

• Data received by the webhook has to be interpreted by custom code that you write, so it can't be used for Template Library inputs.

When a webhook has been created, you will be given 3 options:

• Copy the entire webhook to your clipboard

• Replace the current webhook URL with a new webhook URL

• Remove the webhook URL from existence

Webhook Status Codes​

No matter which language or service you use to run the POST request, you will see the following status codes returned.

201 - Created Successfully​

When your POST request returns a status code of 201, your entity has been successfully scheduled.

{
   "request" : {
      "id" : "955939cc-2b90-4b8e-bf23-7375cd87822b"
   },
   "data" : {
      "fleet_id" : "cc3737df-06ee-431a-8f87-1e79f1eed6d6",
      "project_id" : "d1680f76-3b3c-420e-bbf3-9d62c6a2b450",
      "org_id" : "2d52c575-989e-4642-bc63-c63408ee3fd8",
      "fleet_run_id" : "ad4d4655-91fd-4499-9a1a-06d6e8a433d4"
   }
}

With this status code, you'll receive back IDs for the element you ran, alongside a unique request ID.

400 - Bad Requests​

When your POST request returns a status code of 400, your request has failed. This is usually due to a webhook URL that is malformed or no longer exists. You'll see the following JSON response returned alongside this status code.

{
   "request" : {
      "id" : "1af80dfc-e1b7-459f-9921-e5cb9e08b684"
   },
   "data" : null
}
​

Additional Notes​

1. Each Workflow can only have one webhook associated to it.

2. Workflowss may not run instantaneously, as there is still time associated with entering a job queue, spinning up servers, and installing any external package dependencies.

Set Up

1. Navigate the specific Workflow that you want to add a webhook to and hover over the webhook icon.

   

2. Click Add Webhook.

Copying/Deleting/Refreshing A Webhook Trigger

1. After creating your Webhook, you can delete it by clicking the red icon and confirming you wish to delete

2. If you need to refresh- you can click the refresh icon

3. The far left copy icon allows you to copy the webhook and use it in other services (Be careful sharing this! Remember - this is like a secret password, and should be treated as such)