Sending a webhook from a Runbook

If you have internal systems that perform tasks like rolling back deployments, you may want to dispatch an HTTP request from FireHydrant to those systems. This article explains how to set up a Runbook step that sends a webhook to an endpoint of your choice.

Adding the webhook step

1. In the left nav, click Runbooks.
2. Click the Runbook where you want the webhook to originate.
3. On the edit page for the Runbook, from the Available Steps section , scroll down to the Send a Webhook step and click Add.

• Endpoint: the target URL you for the webhook.
• HMAC Secret: a short string you can then use to verify that the webhook came from FireHydrant in your application.
• JSON Payload: FireHydrant uses liquid templating syntax to interpolate values into a JSON string to send to your endpoint. For more information about template syntax, you can always visit the FireHydrant templating docs or the FireHydrant API to see the API payload structure.
• JSON Headers: You can specify needed headers for the request here.
  • By default, the Webhook step's method is POST. To override, specify an additional argument here for X-HTTP-Method-Override, like so:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer example-token-123",
  "X-HTTP-Method-Override": "PATCH"
}

JSON Payload Templating

You can format the payload to be sent to your endpoint however you like, as long as the result is in valid JSON format. If you'd like to include a JSON version of certain parts of the payload, you can also use liquid filters to convert input to JSON. For example:

#{{ incident.labels | toJSON }}

This converts the labels attribute on the incident to JSON so it can easily be sent in the JSON payload:

{ "incident_id": "#{{incident.id}}", "labels": #{{ incident.labels | toJSON }}}

This lets you easily include whatever data you'd like in the payload.

Note: If you are sending incident data or parameters that may contain new lines (e.g. Incident Description, Custom Impact, etc.), make sure you use toJSON to escape the newlines, otherwise it will insert as literal newlines in the request body.

Signature Verification

Every payload request you receive from FireHydrant will have a fh-signature header containing the computed signature of your HMAC Secret and the JSON payload. FireHydrant uses SHA256 to compute the signature.

Using Ruby as an example, you could use the following code to calculate the signature with the secret key and check it against the one received:

key = "super-secret-key"
data = request.body
signature = headers['Fh-Signature']
if signature == OpenSSL::HMAC.hexdigest("SHA256", key, data)
    # perform taskend

Organization Secrets

When configuring your Runbook webhook step, sometimes you'll want to make use of secret values such as tokens or other items needed in authorization headers.

You can configure this under Organization > Secrets.

These secrets are encrypted when stored and will not be visible when used inside the Runbook step or within the UI after initial creation.

You can make use of these secrets by referring to their keys via the secrets Liquid variable:

If you end up using dashes in the key of the secret, Liquid templating may run into issues trying to refer to it using standard dot notation.

So instead of referring to the variable like this:

{{ secrets.something-with-dashes }} 

You should instead use the property notation:

{{ secrets['something-with-dashes'] }}

Note: Organization secrets are currently only usable inside the Runbook's Webhook step.