Webhooks

How webhooks work

A webhook endpoint is a URL on your side plus a list of event types. When a matching event happens, Halyard sends it as a JSON POST, signed with a secret only you and Halyard know.

• At-least-once delivery. An event can arrive more than once; deduplicate on its id.
• No ordering guarantee. Use created_at or fetch the job if order matters.
• Fast acknowledgement. Respond with any 2xx within 10 seconds, then do the slow work in the background, for example in a Halyard job.

Set up an endpoint

1. Expose an HTTPS route

   Add a POST route to your app, like /webhooks/halyard. It must be reachable from the internet over HTTPS with a valid certificate. During development, use the CLI instead.

2. Register the endpoint

   Create it in the dashboard under Settings → Webhooks, or through the API:

   Create an endpointcURLNode.jsPython

   curl https://api.halyard.example/v3/webhook_endpoints \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -H "Content-Type: application/json" \  -d '{    "url": "https://app.northwind.example/webhooks/halyard",    "events": ["job.failed", "job.dead_lettered", "schedule.skipped"],    "description": "Alerting"  }'

3. Store the signing secret

   The response includes a whsec_ secret. It is shown once; store it as HALYARD_WEBHOOK_SECRET in your secret manager. Each endpoint has its own secret.

4. Verify, acknowledge, process

   Check the signature, return 204, and hand the event to a background job. The rest of this page covers each part.

Event payload

Every delivery has the same envelope. Headers identify the delivery and carry the signature:

POST /webhooks/halyard HTTP/1.1Host: app.northwind.exampleContent-Type: application/jsonUser-Agent: Halyard-Webhooks/3.4Halyard-Delivery: dlv_2Hx7Kc9Me4Halyard-Signature: t=1791970331,v1=5f0c8e1a9b3d47c2e6a1f08b7d94c3e2a5b6f1d0c9e8a7b6d5c4f3e2a1b0c9d8

{  "id": "evt_4Zr8Nq1Tx6",  "type": "job.failed",  "created_at": "2026-10-14T09:32:11Z",  "api_version": "v3",  "livemode": false,  "data": {    "job": {      "id": "job_3Rk9Tq7Xw2",      "queue": "emails",      "task": "send-welcome-email",      "status": "retrying",      "attempt": 2,      "max_attempts": 5,      "next_attempt_at": "2026-10-14T09:37:11Z",      "last_error": {        "message": "SMTP timeout after 10s",        "class": "TimeoutError"      }    }  }}

Verify signatures

Anyone can send a POST to your endpoint. The Halyard-Signature header proves a delivery came from Halyard and wasn't changed or replayed. It looks like t=1791970331,v1=5f0c8e…, and you verify it in four steps:

1. Split the header on , and read t (Unix seconds) and every v1 value.
2. Build the signed string: the timestamp, a literal ., then the raw request body.
3. Compute an HMAC with SHA-256 over that string using your endpoint secret, as lowercase hex, and compare it to each v1 in constant time.
4. Reject the delivery if no signature matches, or if t is more than 5 minutes from your clock.

import crypto from "node:crypto"; const TOLERANCE_SECONDS = 300; export function verifyHalyardSignature(rawBody, header, secret) {  const items = header.split(",").map((part) => part.split("="));  const timestamp = Number(items.find(([k]) => k === "t")?.[1]);  const signatures = items.filter(([k]) => k === "v1").map(([, v]) => v);   if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) {    throw new Error("Timestamp outside tolerance");  }   const expected = crypto    .createHmac("sha256", secret)    .update(`${timestamp}.${rawBody}`)    .digest("hex");   const valid = signatures.some(    (sig) =>      sig.length === expected.length &&      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),  );  if (!valid) throw new Error("No matching signature");   return JSON.parse(rawBody);}

import hashlibimport hmacimport jsonimport time TOLERANCE_SECONDS = 300  def verify_halyard_signature(raw_body: bytes, header: str, secret: str) -> dict:    items = [part.split("=", 1) for part in header.split(",")]    timestamp = int(next((v for k, v in items if k == "t"), 0))    signatures = [v for k, v in items if k == "v1"]     if abs(time.time() - timestamp) > TOLERANCE_SECONDS:        raise ValueError("Timestamp outside tolerance")     signed = f"{timestamp}.".encode() + raw_body    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()     if not any(hmac.compare_digest(expected, sig) for sig in signatures):        raise ValueError("No matching signature")     return json.loads(raw_body)

package webhooks import (	"crypto/hmac"	"crypto/sha256"	"encoding/hex"	"errors"	"strconv"	"strings"	"time") const tolerance = 5 * time.Minute func Verify(body []byte, header, secret string) error {	var ts int64	var sigs []string	for _, part := range strings.Split(header, ",") {		k, v, _ := strings.Cut(part, "=")		switch k {		case "t":			ts, _ = strconv.ParseInt(v, 10, 64)		case "v1":			sigs = append(sigs, v)		}	}	if ts == 0 || time.Since(time.Unix(ts, 0)).Abs() > tolerance {		return errors.New("timestamp outside tolerance")	} 	mac := hmac.New(sha256.New, []byte(secret))	mac.Write([]byte(strconv.FormatInt(ts, 10) + "."))	mac.Write(body)	expected := hex.EncodeToString(mac.Sum(nil)) 	for _, sig := range sigs {		if hmac.Equal([]byte(sig), []byte(expected)) {			return nil		}	}	return errors.New("no matching signature")}

require "json"require "openssl" TOLERANCE_SECONDS = 300 def verify_halyard_signature(raw_body, header, secret)  items = header.split(",").map { |part| part.split("=", 2) }  timestamp = items.find { |k, _| k == "t" }&.last.to_i  signatures = items.select { |k, _| k == "v1" }.map(&:last)   if timestamp.zero? || (Time.now.to_i - timestamp).abs > TOLERANCE_SECONDS    raise ArgumentError, "Timestamp outside tolerance"  end   expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")  unless signatures.any? { |sig| OpenSSL.secure_compare(sig, expected) }    raise ArgumentError, "No matching signature"  end   JSON.parse(raw_body)end

Rotating secrets

Roll a secret from the dashboard or with POST /webhook_endpoints/:id/roll_secret. For 24 hours by default, Halyard signs every delivery with both the old and the new secret, so the header carries two v1 values. Deploy the new secret any time in that window; the code above accepts either.

Retries and delivery

A delivery succeeds when your endpoint answers 2xx within 10 seconds. Anything else, including redirects and timeouts, counts as a failure and is retried on this schedule:

• After 10 failed attempts the delivery is marked failed. It stays visible in the dashboard for 30 days and you can resend it with one click.
• If every delivery to an endpoint fails for three days, the endpoint is disabled and we send an endpoint.disabled event to your other endpoints and an email to project owners.
• Requests come from a fixed set of IP addresses per region, listed on the Security page, if your firewall needs them.

Test locally

The Halyard CLI opens a tunnel from your test project to your machine, so you can receive real deliveries on localhost without exposing anything.

# Log in once; the CLI stores a test-mode key for this machine.halyard login # Forward deliveries for your test project to a local server.halyard listen --forward-to localhost:3000/webhooks/halyard> Ready. Signing secret for this session: whsec_cli_Jr4Wd8Hs2V> Forwarding job.*, queue.*, schedule.* to http://localhost:3000/webhooks/halyard

# In a second terminal: send a realistic test event.halyard trigger job.failed # Re-send a real delivery from the last 30 days to your local server.halyard events resend evt_4Zr8Nq1Tx6 --forward-to localhost:3000/webhooks/halyard

Event types

Subscribe to the types you need, or use a wildcard like job.*. New types are added in minor releases and never sent to endpoints that didn't subscribe to them, except through wildcards.

Best practices