Webhooks

Where the API is you pulling, webhooks are Alma pushing — point one at your endpoint and Alma calls it when a workflow finishes.

Creating a webhook

Click New webhook and provide:

• Endpoint URL — must be https://
• Events — which to subscribe to

The webhook’s name is derived from the URL’s host automatically.

Payload

workflow.completed and workflow.failed deliver:

{
  "workflow_id": "...",
  "execution": {
    "id": "...",
    "status": "completed",
    "trigger_type": "schedule",
    "response_content": "...",
    "completion_summary": "...",
    "error": null,
    "started_at": "...",
    "completed_at": "..."
  }
}

Headers

Content-Type: application/json
User-Agent: Alma-Webhooks/1
X-Alma-Event: workflow.completed
X-Alma-Delivery-Id: <delivery id>
X-Alma-Timestamp: <ms epoch>
X-Alma-Signature: sha256=<hex HMAC-SHA256>

Verifying the signature

The signature covers {timestamp}.{body}, not the body alone — signing the body alone will never match. This also lets you reject replays: check that X-Alma-Timestamp is recent before trusting the payload.

import { createHmac, timingSafeEqual } from "node:crypto";
 
function verify(rawBody, headers, secret) {
  const timestamp = headers["x-alma-timestamp"];
  const signature = headers["x-alma-signature"];
 
  if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false;
 
  const expected =
    "sha256=" +
    createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
 
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Secrets are prefixed whsec_.

Delivery

Alma retries failed deliveries 5 times with exponential backoff. Any non-2xx response counts as a failure. Timeout is 10 seconds.

Redirects aren’t followed — a 3xx counts as a failed attempt, since following one could bounce the delivery somewhere it shouldn’t go. Return a 2xx quickly and do your work afterward.

Auto-disable

15 consecutive failures disables an endpoint automatically, with the reason shown on its detail page. Fix the endpoint, then click Enable. The counter resets on any success.

Monitoring

The detail page has Send test, Rotate secret, and Disable/Enable, plus a Recent deliveries table with event, status, code, duration, and any error text.

URL restrictions

Endpoints must be https:// and publicly addressable. Alma rejects localhost, .local, .internal, and private or link-local IP ranges, both at creation and on every send.

Limits

A workspace can have 20 endpoints.