Agent skill
Column Webhooks Skill
Receive and verify Column webhooks. Use when setting up Column bank webhook handlers, debugging Column-Signature verification, or handling events like ach.outgoing_transfer.completed, ach.outgoing_transfer.returned and book.transfer.completed.
Install this skill
npx skills add hookdeck/webhook-skills --skill column-webhooks
When to Use This Skill
- How do I receive Column webhooks?
- How do I verify the
Column-Signatureheader? - How do I handle
ach.outgoing_ortransfer.completed book.transfer.completedevents? - Why is my Column webhook signature verification failing?
- Is the
Column-Signaturehex or base64?
Essential Code (USE THIS)
Every Column delivery carries Column-Signature: the bare lowercase hex HMAC-SHA256 of the raw request body, keyed with the signing secret of the endpoint that received it (Dashboard → Webhook settings; each endpoint has its own secret). No prefix, no timestamp, no list of values. Only the body is signed.
Column's docs don't state the output encoding. Two production integrations (hackclub/hcb, formancehq/payments) confirm hex.
Verification (Node.js)
const crypto = require('crypto');
// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyColumn(rawBody, signature, secret) {
if (!secret || typeof signature !== 'string') return false;
// 64 hex chars first: Buffer.from(x, 'hex') silently drops invalid characters
if (!/^[0-9a-f]{64}$/i.test(signature)) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}
Verification (Python)
import hashlib, hmac, re
def verify_column(raw_body: bytes, signature: str, secret: str) -> bool:
if not secret or not signature:
return False
signature = signature.lower()
if not re.fullmatch(r"[0-9a-f]{64}", signature):
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest().encode()
return hmac.compare_digest(signature.encode(), expected) # bytes on both sides
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Reject a missing, empty, malformed or mismatched signature with 401.
No timestamp window
Column signs the body only. There is no timestamp to check and no replay window to enforce; don't invent one from unsigned headers or body fields. Deliveries are at-least-once and redeliveries keep the same event id (evnt_...), so deduplicate on it. Ordering is not guaranteed.
Event Types
Column sends 212 documented event types, named {category}.{action} or {category}.{sub_. Dispatch on the body's top-level type field; no header names the type. The examples handle these and log the rest:
type | Fires |
|---|---|
ach.outgoing_ | An outgoing ACH transfer completed |
ach.outgoing_ | An outgoing ACH transfer was returned |
book.transfer.completed | A book transfer between Column accounts completed |
Other documented types include book.transfer.hold_, book.transfer.updated, book.transfer.canceled, ach.outgoing_, ach.outgoing_, ach.outgoing_ and ach.outgoing_. See references/overview.md for the payload and the full list link.
Important Headers
| Header | Description |
|---|---|
Column-Signature | Lowercase hex HMAC-SHA256 of the raw body |
Webhook-Endpoint-Id | Which webhook endpoint this delivery is for |
Environment Variables
COLUMN_WEBHOOK_SECRET=your_endpoint_signing_secret # per-endpoint secret from the Dashboard
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 column --path /webhooks/column
Reference Materials
- references/overview.md - Column webhook concepts, events, payload, retries
- references/setup.md - Creating an endpoint and finding its signing secret
- references/verification.md - Signature details, gotchas, and debugging