Authenticate Webhook Payloads

Securely validate webhook events sent from Reflex using HMAC-SHA256 signatures.

Overview

Webhook secrets provide a way to verify that incoming webhook requests really originate from Reflex. Each team has a unique webhook_secret that is used for signing webhook events.

When an event is triggered, Reflex sends a POST request to the configured webhook URL with an Amboss-Secret header. This header contains an HMAC-SHA256 signature of the webhook payload, signed using the webhook_secret.

Retrieving Webhook Secret

To validate webhook requests, you need your webhook_secret. You can retrieve it using the following GraphQL query or directly in the settings view  in Reflex.

query Team {
  getUser {
    team {
      webhook_secret
    }
  }
}

{
  "data": {
    "getUser": {
      "team": {
        "webhook_secret": "df21d54f-618a-4dce-b796-be1ea0ee6716"
      }
    }
  }
}

Validating Webhook Requests

How to Compute the Hash

const crypto = require("crypto");
 
function computeHash(webhook_payload, webhook_secret) {
  const hash = crypto
    .createHmac("sha256", webhook_secret)
    .update(Buffer.from(JSON.stringify(webhook_payload), "utf8"))
    .digest("hex")
    .toLowerCase();
 
  return hash;
}

import hmac
import hashlib
import json
 
def computeHash(webhook_payload, webhook_secret):
    hash = hmac.new(webhook_secret.encode("utf-8"),
        msg=bytes(json.dumps(webhook_payload), "utf-8"),
        digestmod=hashlib.sha256).hexdigest().lower()
 
    return hash

Each computeHash() function:

• Generates an HMAC-SHA256 hash of the received payload using your webhook_secret.
• Encodes the payload consistently by converting it to a UTF-8 JSON string before hashing.
• Returns the final hash so it can be compared against the Amboss-Secret header.

Example

You can use this example to validate your hashing logic.

Webhook Secret

df21d54f-618a-4dce-b796-be1ea0ee6716

Webhook Payload

{
  "event": "WORKFLOW_RESULT",
  "payload": {
    "workflow_run_id": "12345",
    "template": {
      "id": "temp_987",
      "name": "Data Processing Workflow",
      "description": "Processes incoming data and generates reports."
    },
    "created_at": "2024-02-12T10:15:30Z",
    "finished_at": "2024-02-12T10:45:00Z",
    "status": "COMPLETED",
    "jobs": [
      {
        "id": "job_001",
        "created_at": "2024-02-12T10:16:00Z",
        "finished_at": "2024-02-12T10:30:00Z",
        "job_name": "Data Ingestion",
        "status": "SUCCESS"
      }
    ],
    "inputs": [
      {
        "input_name": "dataset_url",
        "value": "https://example.com/dataset.csv"
      }
    ]
  }
}

Computed HMAC-SHA256 Hash

8548e12b87d55549d2ef9c1f11e4afe00c56ccbd1528fa4a2d654fd6ef998609

Checks

• This computed hash should be compared with the value of the Amboss-Secret header.
• If both values match, it confirms that the request is authentic and unaltered, ensuring that it was sent by Reflex and not modified in transit.
• If they do not match, the request should be rejected as it may have been tampered with or sent by an unauthorized source.

Troubleshooting