What are Webhooks?
Webhooks are automated messages sent from apps when something happens. They have a message—or payload—and are sent to a unique URL—on another server to communicate from application to application. More on understanding webhooks from our friends at Zapier.
What you can do with Webhooks
Want to update another system when a step in Manifestly is completed? Webhooks!
Want to send information to another server when a workflow run is completed? Webhooks!
Events Available
- Run start
- Run complete
- Run is late
- Step complete
- Step is late
Payload
You have two options with respect to the json payload sent in our webhooks. Use the built in json described below or create your own custom json.
Standard JSON payload
When a web hook is called after one of these events, json will be sent formatted like the following. Things to note:
- For every event, the full json for the run as well as every step in the run is sent
- For workflows with data collection, the data array is sent within each step
- For step webhooks, the current step is listed both in the steps array as well as at the root of the json payload
{
"participants": "philip@manifest.ly, mark@manifest.ly",
"workflow_name": "Employee Onboarding",
"checklist_run_detailed_name": "John Smith - Employee Onboarding",
"checklist_run_name": "John Smith",
"completed_at": "2022-08-30T15:37:53.565Z",
"completed_by_email": "philip@manifest.ly",
"completed_by_name": "Philip Crawford",
"run_id": 43682,
"run_url": "http://app.manifest.ly/runs/43682/edit",
"external_id": null,
"tags": ["Management"],
"archive_url": "http://app.manifest.ly/runs/archives/2f9ccd4ff927cc8a32c295c50ddb1d97.pdf",
"started_at": "2022-08-30T15:00:25.084Z",
"late_at": null,
"data_first_name": "John",
"steps": {
"step_2051": {
"title": "Before First Day",
"header": "Header",
"assigned_to": null,
"assigned_to_email": null,
"completed_at": null,
"completed_by_email": null,
"completed_by_name": null,
"data": {},
"late_at": null,
"run_step_id": 30845218,
"skipped": false,
"step_id": 2051
},
"step_2052": {
"title": "Add to Slack",
"add_to_slack": "Add to Slack",
"assigned_to": null,
"assigned_to_email": null,
"completed_at": null,
"completed_by_email": null,
"completed_by_name": null,
"data": {},
"late_at": null,
"run_step_id": 30845219,
"skipped": false,
"step_id": 2052
},
"step_2054": {
"title": "Enter in HRIS",
"enter_in_hris": "Enter in HRIS",
"assigned_to": null,
"assigned_to_email": null,
"completed_at": "2022-08-30T16:32:40.296Z",
"completed_by_email": "philip@manifest.ly",
"completed_by_name": "Philip Crawford",
"data": {
"data_223": {
"value": "John",
"first_name": "John",
"label": "First Name",
"valid_values": null
}
},
"late_at": null,
"run_step_id": 30845220,
"skipped": false,
"step_id": 2054
},
"step_2059": {
"title": "Create email address",
"create_email_address": "Create email address",
"assigned_to": null,
"assigned_to_email": null,
"completed_at": null,
"completed_by_email": null,
"completed_by_name": null,
"data": {},
"late_at": null,
"run_step_id": 30845221,
"skipped": false,
"step_id": 2059
}
},
"step": {
"title": "Enter in HRIS",
"enter_in_hris": "Enter in HRIS",
"assigned_to": null,
"assigned_to_email": null,
"completed_at": "2022-08-30T16:32:40.296Z",
"completed_by_email": "philip@manifest.ly",
"completed_by_name": "Philip Crawford",
"data": {
"data_223": {
"value": "John",
"first_name": "John",
"label": "First Name",
"valid_values": null
}
},
"late_at": null,
"run_step_id": 30845220,
"skipped": false,
"step_id": 2054
},
"step_title": "Enter in HRIS",
"skipped": false,
"data": "John",
"data_label": "First Name",
"data_required": true,
"run_step_id": 30845220
}Custom JSON payload
You also have the ability to fully customize the JSON sent in these webhooks.
Also, within the custom JSON, you can use content variables to send data from the workflow, run, or user who completed the step in that customized JSON payload.
With this custom JSON payload, you can do all sorts of integrations with virtually every platform. Send highly interactive messages in Slack or MS Teams, send data to a server, or connect directly with an integration platform.
{
"text": "Hello, world. This is a message from Manifestly. 🙂"
}Securing Your Hook Endpoints
When setting up web hooks, you might want to consider ways to make sure only valid posts are executed at those endpoints.
There are several ways to secure web hooks.
Set up an API Key with the name ‘webhook’
When you create an API Key with the name of “webhook”, Manifestly will send that key value with every web hook execution. On your side, you can filter out requests that do not have this key value.
Limit by hostname
Limit your running of the hooks by looking at the hostname. They will come from manifest.ly
Limit by IP address
Manifestly does not currently have the ability to provide a specific IP range, due to our hosting platform. We are working on an update with our host that will let us provide an IP range.