Webhook Trigger

Start an instance of a Workflow when a system calls a webhook URL. Webhook triggers are highly configurable and great for automatically starting a instance of a Workflow when an event happens in another system. They are a straightforward and dependable way to build custom on-the-fly integrations with one of your company’s applications.

What are webhooks?

Webhooks are a way that your apps or services can send information to PagerDuty Workflow Automation. You can think of webhooks as ways that apps can speak to and notify each other. With a webhook trigger, you can “listen” for these notifications from your other apps or services, and start a Workflow instance for every notification. PagerDuty Workflow Automation can also send a response back to the system that sent the notification.

When a system calls the webhook URL and starts a Workflow, it can also pass along information, including fields, data tables and files. Whatever values or data is passed to the webhook can be used in your automation; it will all be turned into easy to reference fields.

If you want to build your own integration with a custom system, a webhook trigger is the best way to do it. If you’d like to use a webhook to set up an integration between PagerDuty Workflow Automation and one of your other systems, give this article to one of your developers to review, or contact PagerDuty Workflow Automation support to get more information.

Use case

You can use a webhook trigger to create endless custom integrations with different systems. With a webhook, you can start an instance from practically any event. Here are just 3 examples:

• A Shopify order is paid
• A GitHub issue is closed
• An invoice is created in a custom accounting application

How to configure this trigger

Setting up a webhook Trigger is a technical process and requires some set up in a 3rd party system like Postman or through cURL. The most technical step is to set up a POST. Once a POST is defined, mapping it to a webhook trigger can be straightforward.

After configuring the trigger, you’ll have a finished webhook URL. After the initial trigger configuration, hit done and reload the trigger page and the webhook URL and any tokens will repopulate into the window. You can always access the URL and tokens by reopening the trigger.

Fields for this trigger

• Trigger name

  • A descriptive name to help distinguish it from other triggers

• Wait for process to complete?

  • Select whether or not a success message should be sent at the beginning or end of a process.
    • If you want to send a success message when the process is complete, select True
      • This is a good choice when you POST information and want to return a custom result back to the originating system. If you POST a username and want to confirm if they have an account, select True to wait for this to finish so the information can be included in a response.

      💡   Tip: This option is subject to a time out after 25 seconds. This is intended to be used with very quick, fully automated processes.

    • If you want to send a standard success message as soon as the process starts, select False
      • This is a good choice when you’re posting information and not using the webhook trigger to return a result back to the originating system. If you POST a GitHub issue ID to automatically close the issue and no response is needed, select False to send a response immediately.

• Do you want to receive a custom response?

  If you selected true for Wait for process to complete, you have the option to send a custom or standard response from the webhook trigger.

  • To send a standard success message, select False

    • The standard success message returns the runID, progesssecret, and the teamName values.

  • To send a custom success message, select True.

    • The custom success message can be configured to return different field references. The custom response template is covered below in the Configure the Response

• Response Content-Type

  • If you selected true for Do you want to receive a custom response, you can select the response content type.
  • Select the format of the expected response. You can pass in values with any of the custom response content types illustrated in the Configure the Response section below.

• Response Template

  • If you selected true for Do you want to receive a custom response, you can select the response template.
  • Based on the response content type, a custom response template is required to send the correct information from PagerDuty Workflow Automation back to the originating system. See Configure the Response below for examples of response templates in various formats.

• Authentication method

  • Anyone with the webhook URL can start the webhook trigger unless you have authentication. Although most people won’t guess the URL, if you only want certain people to be able to start the trigger or if the response discloses confidential information, you should set up basic auth or a token as standard authentication for API calls.

    • None
    • Basic Auth
      • Username - The username you will pass in the API header
      • Password - The password you will pass in the API header
    • Token
      • When using a token, the token needs to be included in the Header with the format: Authorization: Token {token-id}
      • After saving the webhook trigger, a default token will be generated. Re-open the trigger to view the token, or replace the default value with a custom token.

How to configure the POST body

The webhook trigger accepts various POST request formats.

• application/json
• text/xml
• multipart/form-data
• application/x-www-form-urlencoded

Configuring the body with JSON

Here is an example POST body formatted so the webhook trigger can interpret the JSON keys, values, and arrays and convert them to fields, field values, and data tables.

  {
  "my-key": "my-value",
  "my-array": [
      {
          "name": "item 1",
          "price": "$10",
          "quantity": 20
      },
      {
          "name": "item 2",
          "price": "$20",
          "quantity": 22
      },
      {
          "name": "item 3",
          "price": "$30",
          "quantity": 2
      }
  ]
  }

Converting key and value pairs into fields

The key and value pair “my-key”: “my-value” is converted into a PagerDuty Workflow Automation field and field value format. Using the example above, the key and value pair,

  {
  "my-key": "my-value"
  }

Is converted into the PagerDuty Workflow Automation field {my-key} with the value my-value. The key will become a field name, and the value will become that field’s value.

Converting arrays into Workflow Automation data tables

The array “my-array” is converted into a Workflow Automation data table. Using the example above, the array,

  {
  "my-array": [
      {
          "name": "item 1",
          "price": "$10",
          "quantity": 20
      },
      {
          "name": "item 2",
          "price": "$20",
          "quantity": 22
      },
      {
          "name": "item 3",
          "price": "$30",
          "quantity": 2
      }
  ]
  }

Is converted into a data table formatted as the example table below shows:

Any data table created through the webhook trigger is accessible at https://{team-name}.pushbot.com/tables/{data-table-id}. A field named my-array with a value of a data table ID is created for any data tables made from an array.

How to configure the response

The webhook trigger can return standard and custom responses after receiving a POST request. Examples of the standard response and the format for the custom response are below.

A custom response is useful if you POST information to the webhook trigger and want to return a custom result back to the originating system. Such as a POST request with a username, then checking within PagerDuty Workflow Automation to see if that username has an active account, then sending a custom response back with true or false based on the user account. A custom response would support this use case.

Standard response

A standard response is sent for all POSTs sent to a webhook trigger unless a custom response is specified.

Standard response template

  {
    "runID":"{run-id}",
    "progressSecret":"{progess-secret}",
    "teamName":"{team-name}"
  }

Standard response output example

  {
    "runID": "3fe4004c-b697-41b5-9f56-887b4b3aaa00",
    "progressSecret": "nP5l2WsK-mMMEqYTW_000xmwRcAAAsdyLYFNciINFXs",
    "teamName": "example"
  }

Example custom response

The custom response supports JSON and XML formatting. An example response template in JSON and XML that responds with a dynamic company name, run ID, and two additional fields follows:

JSON Response Template

Custom JSON response template

  {
    "company name":"",
    "one": "",
    "two": "",
    "runID": ""
  }

Custom JSON response output

  {
    "company name": "PagerDuty Workflow Automation",
    "one": "example field one value",
    "two": "example field two value",
    "runID": "3fe4004c-b697-41b5-9f56-887b4b3aaa00"
  }

XML Response Template

Custom XML response template

  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
    <company name></one>
    <one></one>
    <two></two>
    <runID></runID>
   </soap:Body>
  </soap:Envelope>

Custom XML response output

  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
    <company name>PagerDuty Workflow Automation</one>
    <one>example field one value</one>
    <two>example field two value</two>
    <runID>3fe4004c-b697-41b5-9f56-887b4b3aaa00</runID>
   </soap:Body>
  </soap:Envelope>

How to connect your system to a webhook trigger

A basic POST request is all that’s required to connect an event in your system to PagerDuty Workflow Automation’s webhook trigger. Key and value pairs, arrays, or even files can be passed to the webhook trigger. Here are a few command line examples using cURL.

Example cURL command formatting to POST to a webhook trigger

application/json example

  curl -d '{json}' -H 'Content-Type: application/json' https://{teamname}.pushbot.com/v1/webhooks/{webhook trigger id}

application/xml example

  curl -d '{xml}' -H 'Content-Type: text/xml' https://{teamname}.pushbot.com/v1/webhooks/{webhook trigger id}

multipart/form-data example

  curl -F key1=value1 -F key2=value2 https://{teamname}.pushbot.com/v1/webhooks/{webhook trigger id}

File example

  curl -F key1=@localfilename1 -F 'key2=@localfilename2' https://{teamname}.pushbot.com/v1/webhooks/{webhook trigger id}

The {webhook trigger id} is a string within the entire payload URL generated during initial webhook trigger configuration. The webhook URL that contains the string will be created after you have configured the trigger. Once the trigger is configured, hit done and reload the trigger page and the payload URL and any tokens will repopulate into the window. This URL is the address for the unique webhook trigger for the POST.

What will this output?

This trigger may output more than one field. Any JSON key value pairs or arrays or other data passed into the Webhook trigger will become fields and field value pairs or data tables. For example, JSON text being converted will output using the example below:

A POST with the body:

  { "firstName": "Mary", "lastName": "Smith" }

Will convert the keys into the fields:

• firstName
• lastName

With the respective fields assigned the value:

• “Mary”
• “Smith”

Any fields that are arrays will also become data tables which are accessible at https://{team-name}.pushbot.com/tables/{data-table-id}. A field named my-array with a value of a data table ID is created for any data tables made from an array.