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_ 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_ 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_ | An outgoing ACH transfer completed | Mark a payout as paid |
ach.outgoing_ | 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_ | 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_ | An outgoing ACH transfer was created | Track lifecycle |
ach.outgoing_ | An outgoing ACH transfer went to manual review | Alert operations |
ach.outgoing_ | An outgoing ACH transfer was submitted | Track lifecycle |
ach.outgoing_ | An outgoing ACH transfer settled | Reconciliation |
ach.outgoing_ | A return was dishonored | Investigate |
ach.outgoing_ | A return was contested | Investigate |
ach.outgoing_ | An outgoing ACH transfer was cancelled | Release reserved funds |
ach.outgoing_ | An outgoing ACH transfer created a hold | Show pending funds |
The rest follow the same naming:
| Family | Examples |
|---|---|
| Incoming ACH | ach.incoming_, .settled, .nsf, .completed, .returned |
| Wires | wire.outgoing_transfer.*, wire.incoming_transfer.*, wire return and drawdown requests |
| Real-time payments | realtime.outgoing_, realtime.incoming_, requests for payment |
| International | swift.outgoing_, swift.incoming_, local.outgoing_, fx_trade.* |
| Checks | check.outgoing_debit.*, check.incoming_debit.*, check.lockbox.* |
| Card issuing | issuing.card.*, issuing.card_, 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_ means the transfer settled at the receiving bank, while ach.outgoing_ 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
- Create a webhook endpoint in the Column Dashboard (Webhook settings), or through the API.
- Set the endpoint URL, for example
https://example.com/webhooks/column. - Choose the events to receive in
enabled_events. Start narrow, for exampleach.outgoing_,transfer.completed ach.outgoing_andtransfer.returned book.transfer.completed, and widen as you build. - 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:
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.
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.
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 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_, decision.issuing.card_, decision.issuing.card_ and decision.issuing.card_ 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_atwith the last state you stored. - Treat terminal states such as
returnedandcanceledas 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 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.
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 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 for free and handle Column webhooks reliably in minutes.