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"
}
Was this helpful?