Creating Webhooks
Introduction
Capacity's Developer Platform enables organizations to proactively contact REST web services and use the services' responses in Guided Conversations and Workflows. Data can be pulled from those services repeatedly by polling, as often as every minute with Automations.
For cases where data needs to be streamed (i.e., pushed) to Capacity, there's an API endpoint that can be used.
Use Case
Let's use the situation where an organization uses Jira by Atlassian for project management. Each time a ticket on a project's Kanban board is marked as Closed, the organization wants a Capacity Workflow to run and close a specific Capacity Helpdesk ticket. There are at least these three ways to enable this:
- In Capacity, using the Jira app in App Center, create a scheduled workflow that checks Jira periodically via Jira's API.
- In Jira, set up an automated email notification to the Capacity Helpdesk, which kicks off an Automation that runs the Workflow.
- In Jira, set up an automation that instantly pushes data about the ticket to a Capacity API endpoint, /webhook.
This article covers the third example.
How to Create
Ensure Webhook Provider (non-Capacity) Compatibility
First, webhooks will only work properly with Capacity if the following requirements are met:
- The webhook can send custom headers you'll need two for Capacity.
- The entire request payload can be configured to comply with Capacity's requirements.
Get Capacity API Keys
You'll need to be a Capacity organization administrator or developer for this step.
Also - If you see an existing key, do not delete it without being certain that it will not break other integrations.
Once you're sure that your webhook provider or platform is compliant, navigate to your Org Settings and click on API Keys under Security, in the left menu bar. You'll see the option to add an API Key. Click "Add", give the key a name.
You'll see these two values, which you'll want to save in a safe place because you can only view them once.
- API Key
- X-Capacity-Id
Configure Your Webhook Provider
Now that you have your Capacity credentials, you'll need to configure the webhook.
Your request should make a POST to the URL https://api.capacity.com/v1/webhooks and have the following header values, substituting your API keys.
'X-Capacity-ID' : 'YOUR_X_CAPACITY_ID'
'Authorization' : 'Bearer YOUR_API_KEY'
The body of your request should look like this, with values for the webhook provider (e.g., jira) , type of event (e.g., jira.ticket_completed), and any attributes that will be needed in Capacity:
{
'service': 'SERVICE_NAME',
'trigger_event_type': "EVENT_TYPE',
'attributes': {
'id' : '12345'
}
}Create a Capacity Automation
The webhook should now properly send a request to a URL in Capacity, but what happens then? You'll want to kick off an Automation, which will then take one of these actions:
- Start a workflow
- Send an email
- Update a ticket
So, navigate to Automations in Capacity's console, and Add a New Automation. Give your automation a name, set the Application to Analytics and the trigger should be on event creation as shown below.
You'll then need to set a condition. This condition will be based on attributes (sent via the Webhook's payload) or event type.
So, using Jira as an example, if you'd set your event type as "jira.ticket_completed" in the webhook request body, your event type in Automations would be "jira.ticket_completed".
Once you've set your condition, create one of three types of actions. Note that
For easy debugging, first create an action that sends an email. Once you're certain the webhook works end-to-end, make your action more complex.
To access the attributes sent to Capacity as part of the request body, use a variable with dot notation for the path. The first parts of the path should be analytics_event.attributes, with the attribute keys appended (as shown below).
The only thing left to do after that is test!
Congratulations! You should be set up to use webhooks in Capacity. Let us know if when you've written a webhook at support@capacity.com. We'd love to hear from you.
Troubleshooting
| Issue | Likely cause(s) | What to do |
| Automation isn't being triggered | HTTP request is not properly formed. Something could be incorrect or missing. | Check the audit log in the webhook provider's software, if one exists. Check the HTTP method, headers, and request sent via the webhook. Check your API key and X-Capacity-ID values. You can test them in the API portal at api.capacity.com |
| Automation condition isn't being met | Logic problem | Make sure that your attributes or event type in the logic statement match the values from the webhook exactly. |
| Attributes aren't appearing | Attributes path is not correct | Check for a mismatch between the path in Capacity and attributes sent via the webhook |
Appendix: Jira Example
If you'd like to try this in Jira, go into a Project's settings, create an Automation, and add values like the ones below. You'll want to use your API keys, and add some attributes.
For instructions on how to create a webhook for Microsoft Teams, click here.