Skip to main content

Webhooks

A webhook sends out events it receives via HTTP requests to a specified URL. They are commonly used by web applications to notify users about significant events in real-time. When an event occurs, the webhook sends the event data to the provided URL, allowing the receiving system to react immediately without needing to constantly check for updates. This setup is efficient for maintaining up-to-date information across integrated systems.

Features​

  • Each Webhook 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 HTTP POST method.
  • Webhook parameters will be used to generate and send a new Event.

Webhook Usage​

In the blink platform, you cant use webhooks when creating an Event-Based Workflows.

Configuration​

  • path - A path for the webhook URL, in plain text.
  • secret - A token that the host will provide for authentication.

Authentication​

Webhook requests are authenticated by a Webhook API Key or Signature. This is passed to the Webhook as part of the webhook URL. Both authentication methods are crucial for providing an additional layer of security by confirming the identity of users or applications accessing the data. This ensures controlled access to sensitive information, reinforces authorization policies, and upholds trust between the client and server.

API Key​

The API Key authentication method, allows the external provider to execute the webhook using only an api key which gets generated for the workflow when using the API Key method.

curl -X POST https://<sub-doamin>.app.blinkops.com/webhooks/<path>?apikey=<apikey>

or

curl -X POST https://<sub-doamin>.app.blinkops.com/webhooks/<path> -H "BLINK-API-KEY: <apikey>"

Signature​

  • The Signature authentication method involves generating a cryptographic signature for each request.

  • This Signature format is based on the following format <timestamp>.<url>.<request body> where:

    • timestamp is the timestamp in numeric format. For example: 892403000

    • Followed by the . character

    • Webhook URL is the full URL of the webhook, including query parameters. For example:
    https://<sub-doamin>.app.blinkops.com/webhooks/<path>

    • Followed by the . character

    • Request body is the raw body of a HTTP POST request.

  • Compute an HMAC of the concatenated string with the SHA256 hash function:

SIG=$(echo -n "$TS.$URL.$BODY" | openssl dgst -sha256 -hmac <apikey>)
  • Add the timestamp and the result to the X-BLINK-SIGNATURE HTTP header in the format: ts=<timestamp>;sig1=<hmac>

Which is then signed with the API Key and included in the request to authenticate its authenticity.

Usage Example:

TS=$(date +%s)
BODY='{"foo": "bar"}'
URL=https://<sub-doamin>.app.blinkops.com/webhooks/<path>
SIG=$(echo -n "$TS.$URL.$BODY" | openssl dgst -sha256 -hmac <apikey>)

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