Creating Webhooks


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

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 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 

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! 


IssueLikely cause(s)What to do
Automation isn't being triggeredHTTP 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
Automation condition isn't being metLogic 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 correctCheck 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.

Was this article helpful?