Webhooks & Events

1. Navigate to Settings → Webhooks in the ARQERA app.
2. Click Add Endpoint and enter your HTTPS URL.
3. Select the event types you want to receive, or choose All Events.
4. Copy the generated signing secret and store it securely in your application.
5. Click Send Test Event to verify your endpoint responds with a 2xx status.

Create a webhook endpoint programmatically with a POST request:

curl -X POST https://app.arqera.io/api/webhooks \
  -H "Authorization: Bearer ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Governance Alerts",
    "url": "https://your-app.com/webhooks/arqera",
    "events": [
      "action.approved",
      "action.rejected",
      "policy.violated",
      "compliance.violation.detected"
    ],
    "secret": "whsec_your_signing_secret"
  }'

Response:

{
  "id": "wh_a1b2c3d4e5f6",
  "name": "Production Governance Alerts",
  "url": "https://your-app.com/webhooks/arqera",
  "events": [
    "action.approved",
    "action.rejected",
    "policy.violated",
    "compliance.violation.detected"
  ],
  "status": "active",
  "created_at": "2026-02-19T14:00:00.000Z"
}

1. ARQERA serializes the payload as canonical JSON (sorted keys, no whitespace).
2. A signed string is constructed: {timestamp}.{canonical_json}
3. The signed string is hashed with HMAC-SHA256 using your webhook secret.
4. The result is sent in the X-Webhook-Signature header as t=timestamp,v1=hash.
5. Your server reconstructs the same hash and compares using constant-time comparison.

import hmac
import hashlib
import json

def verify_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    """Verify ARQERA webhook signature.

    Args:
        payload_body: Raw request body bytes.
        signature_header: Value of X-Webhook-Signature header.
        secret: Your webhook signing secret.

    Returns:
        True if the signature is valid.
    """
    # Parse the signature header: "t=<timestamp>,v1=<hash>"
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    timestamp = parts["t"]
    received_sig = parts["v1"]

    # Reconstruct the signed payload
    payload_str = json.dumps(
        json.loads(payload_body),
        sort_keys=True,
        separators=(",", ":"),
    )
    signed_payload = f"{timestamp}.{payload_str}"

    # Compute expected signature
    expected_sig = hmac.new(
        secret.encode("utf-8"),
        signed_payload.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(expected_sig, received_sig)

import crypto from "crypto";

function verifyWebhook(
  payloadBody: string,
  signatureHeader: string,
  secret: string
): boolean {
  // Parse the signature header: "t=<timestamp>,v1=<hash>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => {
      const [k, ...v] = p.split("=");
      return [k, v.join("=")];
    })
  );
  const timestamp = parts["t"];
  const receivedSig = parts["v1"];

  // Reconstruct the signed payload
  const parsed = JSON.parse(payloadBody);
  const canonical = JSON.stringify(parsed, Object.keys(parsed).sort());
  // Remove spaces after separators to match Python's separators=(",",":")
  const compact = canonical.replace(/: /g, ":").replace(/, /g, ",");
  const signedPayload = `${timestamp}.${compact}`;

  // Compute expected signature
  const expectedSig = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSig),
    Buffer.from(receivedSig)
  );
}

# Python SDK
from arqera import Arqera

client = Arqera(api_key="ak_...")
is_valid = client.webhooks.verify(
    payload=request.body,
    signature=request.headers["X-Webhook-Signature"],
    secret="whsec_...",
)

# TypeScript SDK
import { Arqera } from "@arqera/sdk";

const client = new Arqera({ apiKey: "ak_..." });
const isValid = client.webhooks.verify(
  req.body,
  req.headers["x-webhook-signature"],
  "whsec_..."
);

The webhook dashboard in Settings → Webhooks provides: