Gareth Wilson Gareth Wilson

Guide to Column Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationPOST /api/webhook_endpoints or the Dashboard
Subscriptionenabled_events, with wildcards. The first-created matching endpoint wins
Signaturehex HMAC-SHA256
Signature headercolumn-signature
Endpoint headerWebhook-Endpoint-Id
Signed contentThe raw request body, unmodified
SecretOne per endpoint. Rotate by replacing the endpoint
BodyJSON
Event routingBody field type
Response windowA 2xx within 10 seconds
RetriesUp to 25 times within 3 days, exponential backoff, the first a minute later
OrderingNot guaranteed
Source IP44.231.156.17

Events and payloads

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

EventTriggered WhenCommon Use Cases
ach.outgoing_transfer.completedAn outgoing ACH transfer completedMark a payout as paid
ach.outgoing_transfer.returnedAn outgoing ACH transfer was returnedReverse the payout, notify the customer
book.transfer.completedA book transfer between Column accounts completedUpdate internal ledgers
book.transfer.hold_createdA book transfer created a holdShow pending funds
book.transfer.updatedA book transfer changedSync state
book.transfer.canceledA book transfer was cancelledRelease reserved funds
ach.outgoing_transfer.initiatedAn outgoing ACH transfer was createdTrack lifecycle
ach.outgoing_transfer.manual_reviewAn outgoing ACH transfer went to manual reviewAlert operations
ach.outgoing_transfer.submittedAn outgoing ACH transfer was submittedTrack lifecycle
ach.outgoing_transfer.settledAn outgoing ACH transfer settledReconciliation
ach.outgoing_transfer.return_dishonoredA return was dishonoredInvestigate
ach.outgoing_transfer.return_contestedA return was contestedInvestigate
ach.outgoing_transfer.canceledAn outgoing ACH transfer was cancelledRelease reserved funds
ach.outgoing_transfer.hold_createdAn outgoing ACH transfer created a holdShow pending funds

The rest follow the same naming:

FamilyExamples
Incoming ACHach.incoming_transfer.scheduled, .settled, .nsf, .completed, .returned
Wireswire.outgoing_transfer.*, wire.incoming_transfer.*, wire return and drawdown requests
Real-time paymentsrealtime.outgoing_transfer.*, realtime.incoming_transfer.*, requests for payment
Internationalswift.outgoing_transfer.*, swift.incoming_transfer.*, local.outgoing_transfer.*, fx_trade.*
Checkscheck.outgoing_debit.*, check.incoming_debit.*, check.lockbox.*
Card issuingissuing.card.*, issuing.card_transaction.*, issuing.card_token.*, issuing.3ds.*, disputes
Lendingloan.created, loan.disbursement.*, loan.payment.*, loan.delinquent, loan.paid_off
Accounts and reportingaccount.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

FieldDescription
idEvent id (evnt_...), stable across redeliveries: use it to deduplicate
created_atWhen the event was created
typeThe event type
dataThe 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:

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_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 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.