Webhook

The Webhook Action will emit Events it receives through Webhooks (HTTP callbacks).

Webhooks are a common way for web applications to notify users of important occurrences. Use the Webhook action to receive alerts from SIEM; get notified when a developer performs a 'git push'; when a user updates a Jira ticket; or when a user posts in Slack.

To create a new webhook address, simply drag on a Webhook Action to create a URL which can receive HTTP data.

Features​ 

  • Each Webhook Action has a unique URL.

  • Specify a path and a secret that must be included in the Webhook in order for an Event to be emitted.

  • Accepts Webhooks using a variety of HTTP methods, e.g.: POST and GET

  • Webhook parameters will be used to generate and emit a new Event.

  • Specify a custom response message, response code and response headers when Event is successfully emitted.

  • Include incoming headers from HTTP requests.

Configuration Options​ 

  • path - A path for the webhook URL, in plain text.

  • secret - A token that the host will provide for authentication.

  • verbs - (Optional) Comma-separated list of HTTP verbs your action should accept.

  • response - (Optional) The response message to the request. Defaults to 'Ok'.

  • response_code - (Optional) The HTTP response code to the request. Defaults to 201.

  • response_headers - (Optional) An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"})

  • include_headers - True by default, include headers from the request in a headers key while the body of the request is nested under a body key.

Emitted Events​ 

The Webhook Action will convert the Webhook payload into a Tines Event.

Authentication 

By default, webhook requests are authenticated by the Webhook Action secret. This is passed to the Webhook Action via as part of the webhook URL: https://tenant.tines.com/webhook/<path>/<secret>.

Alternative methods of authentication are available:

Authorization Header 

If you wish to use the HTTP Authorization header you can pass the Webhook Action secret as the credential using a Basic auth scheme:

curl -H "Authorization: Basic <secret>" https://tenant.tines.com/webhook/<path>

Signatures 

An alternative to sending the secret with every request is to sign your webhook request with the secret. The process to signing each request is as follows:

  • Generate a timestamp, milliseconds or seconds from epoch works great.

  • Concatenate the timestamp into a String of the format <timestamp>.<webhook URL>.<request body> where:

    • timestamp is the timestamp in numeric format. For example, 1686567186

    • Followed by the . character

    • webhook URL is the full URL of the webhook, including query parameters. For example, https://tenant.tines.com/webhook/<path>

    • Followed by the . character

    • request body is the raw body of a HTTP POST request. This can be left blank for HTTP GET requests

  • Compute an HMAC of the concatenated String with the SHA256 hash function. Use the Webhook Action secret as the key.

  • Add the timestamp and the result to the X-Tines-Signature HTTP header in the format: ts=<timestamp>;sig1=<hmac>.

Here are some examples for HTTP GET and POST requests:

GET

TS=$(date +%s)

URL="https://tenant.tines.com/webhook/<path>?foo=bar"

SIG=$(echo -n "$TS.$URL." | openssl dgst -sha256 -hmac <secret>)

curl $URL -H "X-Tines-Signature: ts=$TS;sig1=$SIG"

POST

TS=$(date +%s)

URL="https://tenant.tines.com/webhook/<path>"

BODY="{'foo': 'bar'}"

SIG=$(echo -n "$TS.$URL.$BODY" | openssl dgst -sha256 -hmac <secret>)

curl -X POST $URL -H "X-Tines-Signature: ts=$TS;sig1=$SIG" -d $BODY

Example Configuration Options​ 

Receive GET and POST requests when the correct path and secret is supplied

{
  "path": "my_webhook_path",
  "secret": "e0d8498269045506b80e2f7a99d041e7",
  "verbs": "get,post"
}

Receive POST requests and respond with a custom response and response_headers.

{
  "path": "my_webhook_path",
  "secret": "e0d8498269045506b80e2f7a99d041e7",
  "verbs": "post",
  "response": "Thank you!",
  "response_code": 200,
  "response_headers": {
    "X-Tines-Response": "Event emitted"
  }
}

Respond with data contained in a resource. Allowed content types are text/plain, text/xml, and application/json.

{
  "path": "my_webhook_path",
  "secret": "882ab799edec692069778fef69064e4b",
  "verbs": "get,post",
  "response_headers": {
    "content-type": "application/json"
  },
  "response": "<<RESOURCE.ip_list>>"
}

Respond to webhook verification challenges using data received by the webhook in the request headers or body.

{
  "path": "my_webhook_path",
  "secret": "882ab799edec692069778fef69064e4b",
  "verbs": "get,post",
  "response": {
    "verification": "<<headers.x_okta_verification_challenge>>"
  }
}

Redirect requests to another address while still recording the data payload.

{
  "path": "my_webhook_path",
  "secret": "882ab799edec692069778fef69064e4b",
  "verbs": "get,post",
  "response": "https://www.google.com",
  "response_code": "302"
}

Response-enabled webhooks 

In stories with the Enable webhook API responses option enabled, the response form the webhook will be event emitted from the first Exit action reached in the story, as long as that action is executed within 30 seconds.

There can be no more than 10 webhook-enabled concurrent responses being processed simultaneously (this limit is higher in dedicated tenants, at 1000). When this limit is exceeded, the webhook action will fall back to responding immediately with the response it has configured.

Was this helpful?