# Column Webhooks

## When to Use This Skill

* How do I receive Column webhooks?
* How do I verify the `Column-Signature` header?
* How do I handle `ach.outgoing_transfer.completed` or `book.transfer.completed` events?
* Why is my Column webhook signature verification failing?
* Is the `Column-Signature` hex 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)

```javascript
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)

```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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/column-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/column-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/column-webhooks/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_category}.{action}`. 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_transfer.completed` | An outgoing ACH transfer completed |
| `ach.outgoing_transfer.returned` | An outgoing ACH transfer was returned |
| `book.transfer.completed` | A book transfer between Column accounts completed |

Other documented types include `book.transfer.hold_created`, `book.transfer.updated`, `book.transfer.canceled`, `ach.outgoing_transfer.initiated`, `ach.outgoing_transfer.manual_review`, `ach.outgoing_transfer.submitted` and `ach.outgoing_transfer.settled`. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/column-webhooks/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

```bash
COLUMN_WEBHOOK_SECRET=your_endpoint_signing_secret   # per-endpoint secret from the Dashboard

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 column --path /webhooks/column

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/column-webhooks/references/overview.md) - Column webhook concepts, events, payload, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/column-webhooks/references/setup.md) - Creating an endpoint and finding its signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/column-webhooks/references/verification.md) - Signature details, gotchas, and debugging