# Guide to Column Webhooks: Features and Best Practices

Column is a nationally chartered bank built for developers. Fintechs and platforms use its APIs to hold deposits and move money over ACH, wires, real-time payments, SWIFT and checks, to issue cards and to originate loans. Money movement is slow and full of states: an ACH transfer is initiated, submitted, settled and only later completed once the return window closes, and it can still be returned or dishonoured along the way. Column's webhooks report every one of those state changes, and for a bank integration they are the main way your ledger stays correct.

This guide covers how Column routes events to endpoints, the main event families, how to verify `Column-Signature`, and the card decision requests that look like webhooks but need a different kind of receiver.

## What are Column webhooks?

A Column webhook endpoint has a URL and an `enabled_events` list. Entries can be exact types such as `ach.outgoing_transfer.returned` or wildcards such as `ach.*` and `*`. Column has a routing rule worth knowing before you create a second endpoint: only the first-created endpoint that matches an event type receives it. Overlapping wildcards don't fan out.

Each endpoint has its own signing secret, generated by Column. Every delivery carries `Column-Signature`, an HMAC-SHA256 of the raw body with that secret, and `Webhook-Endpoint-Id`, which names the endpoint the event was sent to.

## Column webhook features

| Feature | Details |
| --- | --- |
| Configuration | `POST /api/webhook_endpoints` or the Dashboard |
| Subscription | `enabled_events`, with wildcards. The first-created matching endpoint wins |
| Signature | hex HMAC-SHA256 |
| Signature header | `column-signature` |
| Endpoint header | `Webhook-Endpoint-Id` |
| Signed content | The raw request body, unmodified |
| Secret | One per endpoint. Rotate by replacing the endpoint |
| Body | JSON |
| Event routing | Body field `type` |
| Response window | A `2xx` within 10 seconds |
| Retries | Up to 25 times within 3 days, exponential backoff, the first a minute later |
| Ordering | Not guaranteed |
| Source IP | `44.231.156.17` |

## Events and payloads

Column documents more than 200 event types. These are the ones most integrations start with:

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `ach.outgoing_transfer.completed` | An outgoing ACH transfer completed | Mark a payout as paid |
| `ach.outgoing_transfer.returned` | An outgoing ACH transfer was returned | Reverse the payout, notify the customer |
| `book.transfer.completed` | A book transfer between Column accounts completed | Update internal ledgers |
| `book.transfer.hold_created` | A book transfer created a hold | Show pending funds |
| `book.transfer.updated` | A book transfer changed | Sync state |
| `book.transfer.canceled` | A book transfer was cancelled | Release reserved funds |
| `ach.outgoing_transfer.initiated` | An outgoing ACH transfer was created | Track lifecycle |
| `ach.outgoing_transfer.manual_review` | An outgoing ACH transfer went to manual review | Alert operations |
| `ach.outgoing_transfer.submitted` | An outgoing ACH transfer was submitted | Track lifecycle |
| `ach.outgoing_transfer.settled` | An outgoing ACH transfer settled | Reconciliation |
| `ach.outgoing_transfer.return_dishonored` | A return was dishonored | Investigate |
| `ach.outgoing_transfer.return_contested` | A return was contested | Investigate |
| `ach.outgoing_transfer.canceled` | An outgoing ACH transfer was cancelled | Release reserved funds |
| `ach.outgoing_transfer.hold_created` | An outgoing ACH transfer created a hold | Show pending funds |

The rest follow the same naming:

| Family | Examples |
| --- | --- |
| Incoming ACH | `ach.incoming_transfer.scheduled`, `.settled`, `.nsf`, `.completed`, `.returned` |
| Wires | `wire.outgoing_transfer.*`, `wire.incoming_transfer.*`, wire return and drawdown requests |
| Real-time payments | `realtime.outgoing_transfer.*`, `realtime.incoming_transfer.*`, requests for payment |
| International | `swift.outgoing_transfer.*`, `swift.incoming_transfer.*`, `local.outgoing_transfer.*`, `fx_trade.*` |
| Checks | `check.outgoing_debit.*`, `check.incoming_debit.*`, `check.lockbox.*` |
| Card issuing | `issuing.card.*`, `issuing.card_transaction.*`, `issuing.card_token.*`, `issuing.3ds.*`, disputes |
| Lending | `loan.created`, `loan.disbursement.*`, `loan.payment.*`, `loan.delinquent`, `loan.paid_off` |
| Accounts and reporting | `account.overdrafted`, `account.frozen`, `reporting.*` statements and summaries, `identity.*` |

Read Column's descriptions carefully, because the names don't always mean what they suggest. `ach.outgoing_transfer.settled` means the transfer settled at the receiving bank, while `ach.outgoing_transfer.completed` means the return window has passed, and Column notes that a completed transfer can still be returned in rare cases.

### Event Payload Structure

| Field | Description |
| --- | --- |
| `id` | Event id (`evnt_...`), stable across redeliveries: use it to deduplicate |
| `created_at` | When the event was created |
| `type` | The event type |
| `data` | The resource as it was when the event fired |

No header names the event type. `Webhook-Endpoint-Id` names the endpoint that received the delivery.

Because `data` is a snapshot from when the event fired, and events can arrive out of order, an older snapshot can arrive after a newer one. Fetch the resource from the API when you need its current state.

## Setting up Column webhooks

1. Create a webhook endpoint in the Column Dashboard (Webhook settings), or through the API.
2. Set the endpoint URL, for example `https://example.com/webhooks/column`.
3. Choose the events to receive in `enabled_events`. Start narrow, for example `ach.outgoing_transfer.completed`, `ach.outgoing_transfer.returned` and `book.transfer.completed`, and widen as you build.
4. Copy the endpoint's signing secret from the Dashboard's Webhook settings and set it as `WEBHOOK_SECRET`. Use the secret as-is: its UTF-8 bytes are the HMAC key (don't hex- or base64-decode it).

Plan endpoints with the first-match rule in mind. If an early endpoint subscribes to `*`, a later one for `issuing.*` receives nothing. To rotate a secret, create a new endpoint and delete the old one, which also means checking where the new endpoint sits in the creation order.

To receive sandbox events on your machine, forward them with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 column --path /webhooks/column

```

## Securing Column webhooks

Compute an HMAC-SHA256 of the raw body with the endpoint's secret and compare it with `Column-Signature` in constant time. Column insists the body be unmodified: no prettifying, re-serialising or trimming. Column's docs don't say whether the signature is hex or base64 and show no example value. Hex is what production integrations use and what Hookdeck's source type expects. See the [verification documentation](https://docs.column.com/working-with-the-api/events-and-webhooks).

```javascript
const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['column-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

If you run several endpoints, pick the secret by `Webhook-Endpoint-Id`. The handler below does that, deduplicates on the event `id`, and stores the event before acknowledging.

```javascript
const express = require('express');

// e.g. { "webh_...": "secret for that endpoint" }
const secretsByEndpoint = JSON.parse(process.env.COLUMN_ENDPOINT_SECRETS || '{}');

function createColumnApp(ledger) {
  const app = express();
  app.post('/webhooks/column', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = secretsByEndpoint[req.get('webhook-endpoint-id')] || process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    let event;
    try {
      event = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
    if (typeof event.id !== 'string' || typeof event.type !== 'string') return res.sendStatus(400);
    try {
      // recordEvent is a no-op for an evnt_ id it has already stored.
      await ledger.recordEvent(event.id, event.type, event.created_at, event.data);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

Column signs only the body and sends no timestamp header. Redeliveries keep the same `id`, so storing it is enough to make retries and replays harmless.

Hookdeck's Column source type verifies `Column-Signature` as a hex HMAC-SHA256 of the raw body with the endpoint's secret. Hookdeck always answers Column with `200`, records a failed check as failed verification and does not forward that request. There is no time window, so a replay from Hookdeck days later still verifies.

> **Make Column webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies every Column event, stores it, and delivers it to your ledger with retries and replay you control, so an outage on your side never leaves a transfer in the wrong state.

## Column webhook limitations and pain points

### Card decision requests can't be queued

**The Problem:** Card authorisations time out or are declined when the issuing endpoint sits behind a queue.

**Why It Happens:** `decision.issuing.card_transaction`, `decision.issuing.card_authentication`, `decision.issuing.card_token` and `decision.issuing.card_token.device_binding` go to the same webhook endpoints as events, but they are synchronous requests that wait for your approve or decline answer, and they are not retried. Anything that acknowledges immediately and processes later, including a gateway, cannot answer them.

**Workarounds:**

* Send decision requests to a dedicated endpoint that answers synchronously, separate from your event endpoints. Column routes decision requests to the most specific matching endpoint.
* Keep that endpoint fast and highly available.

**How Hookdeck Can Help:** Use Hookdeck for Column's asynchronous events, and keep decision requests on a direct endpoint. Don't put a Hookdeck source in the decision path.

### The signature encoding isn't documented

**The Problem:** It's unclear whether to compare hex or base64, and there's no test vector.

**Why It Happens:** Column's docs say HMAC-SHA256 but never state the output encoding or show a header value.

**Workarounds:**

* Compare hex, which is what production integrations use.
* Verify your code against a real sandbox delivery before going live.

**How Hookdeck Can Help:** Hookdeck's Column source type already expects hex, so you don't need to settle the question in your own code.

### First-match routing between endpoints

**The Problem:** A new endpoint receives nothing, even though its `enabled_events` match.

**Why It Happens:** Only the first-created endpoint that matches an event type receives it. An earlier endpoint with a broad wildcard takes everything.

**Workarounds:**

* Use one endpoint per consumer with non-overlapping event lists.
* Or use a single endpoint and fan out internally.

**How Hookdeck Can Help:** Point one Column endpoint at Hookdeck and use connections and filters to route each event family to a different service.

### Out-of-order delivery over three days

**The Problem:** A `returned` transfer is shown as `completed` because an older event arrived later.

**Why It Happens:** Column retries for up to 3 days and doesn't guarantee ordering. A failed `settled` can arrive after `completed` or `returned`.

**Workarounds:**

* Apply events by comparing `created_at` with the last state you stored.
* Treat terminal states such as `returned` and `canceled` as final.

**How Hookdeck Can Help:** Hookdeck accepts events as soon as Column sends them, which shortens Column's retry gaps, and its event log makes ordering issues easy to see and replay.

## Best practices

### Keep the body untouched

Column says not to prettify, re-serialise or trim the body. Use `express.raw({ type: '*/*' })` in Express, `await request.arrayBuffer()` in Next.js and `await request.body()` in FastAPI, and make sure no `express.json()` runs before your route.

### One secret per endpoint

Using one endpoint's secret on another's deliveries fails every check. Key secrets by `Webhook-Endpoint-Id`.

### Deduplicate on the event `id`

Column keeps the `evnt_` ID across redeliveries. Store it in the same transaction as the ledger change. [Webhook idempotency](/webhooks/guides/implement-webhook-idempotency) explains why the key and the change belong together.

### Acknowledge within 10 seconds

Verify, store and answer `2xx`, then do the ledger work. More on that in [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### Allowlist Column's IP

Column publishes one egress IP, `44.231.156.17`. Use it at your firewall as an extra layer alongside signature verification.

## Conclusion

Column's webhooks are rich and well behaved, with stable event IDs and three days of retries. The traps are structural: first-match routing between endpoints, unordered delivery, an undocumented signature encoding, and card decision requests that share the endpoint but need a synchronous answer. Separate the decision path, verify the hex HMAC, and apply events by `created_at`.

[Hookdeck Event Gateway](https://hookdeck.com) handles the asynchronous side: it verifies each event, keeps a full history and routes each family to the service that owns it.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Column webhooks reliably in minutes.