Skip to content
HookDeploy

GoCardless webhooks

Last verified against GoCardless's documentation on September 27, 2026.

On this page ↓

GoCardless sends webhooks when something happens to a Direct Debit mandate, a payment, a payout, or a subscription. Its webhooks come in batches, carry events whose order isn’t guaranteed, and use a status code most frameworks don’t know, 498, for signature failures. GoCardless is explicit about the right pattern: verify, respond fast, store the body, and fetch the current state from the API before acting. This page covers what GoCardless sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What GoCardless sends webhooks for

ResourceExample actionsTypical use
Mandatescreated, active, cancelled, failed, expiredKnow when you can collect
Paymentscreated, submitted, confirmed, paid_out, failed, charged_backMark invoices paid and handle failures
PayoutspaidReconcile money arriving in your account
Subscriptionscreated, payment_created, cancelled, finishedKeep recurring billing in sync
Refundscreated, paid, failedRecord refunds

Each request contains an events array. Every event has an id, a resource_type, an action, links to the affected resources, and details with a normalized cause.

How GoCardless delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON body containing an events array
Signature headerWebhook-Signature: hex HMAC-SHA256 of the raw body, keyed with the endpoint’s secret
EnvironmentThe Origin header is https://api.gocardless.com for live and https://api-sandbox.gocardless.com for sandbox
Timeout10 seconds
SuccessAny 2xx
Don’t retry498 for an invalid signature, and 204 for event types you don’t recognize
Retries9 delivery attempts in total (1 initial and 8 retries) at increasing intervals
HistoryWebhooks from the past 3 months are in the dashboard, with manual retry
OrderingNot guaranteed. Fetch the resource’s current state from the API
DeduplicationEach event’s id. Not meta.webhook_id, which identifies the delivery attempt
Source IPsThree published static IPv4 addresses

Common GoCardless webhook errors and how to fix them

Signature never matches

  • Parsed body. Hash the raw bytes. Re-serializing the JSON changes them.
  • Wrong secret. Each endpoint has its own secret. Use it as-is, not base64-decoded.
  • Sandbox versus live. Check the Origin header to see which environment sent it.

Invalid signatures keep coming back

GoCardless retries any non-2xx except 498. Answer bad signatures with 498, not 400 or 401, or GoCardless retries them 8 times.

Payments processed in the wrong state

Events arrive out of order: a payments.confirmed can land before payments.created. Don’t infer state from the sequence. Fetch the payment from the API and act on what it says now.

Only the first event processed

Each request is a batch. Loop over the whole events array.

Unknown event types cause retries

GoCardless adds new event types without notice. Return 204 for types you don’t handle, not an error.

Why use HookDeploy with GoCardless

Capture every batch

HookDeploy captures every GoCardless webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down for longer than GoCardless’s 9 attempts, the batches are still in HookDeploy.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

Allowlist GoCardless’s IPs

GoCardless publishes three static IPv4 addresses, so HookDeploy’s IP allowlist works. Add them on the endpoint’s Security tab, under Network, and anything else is rejected before it’s captured. IP allowlists are available on Starter and above.

One webhook, many systems

Send each GoCardless event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems GoCardless can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive GoCardless events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live GoCardless events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Your handler’s 498 stays with HookDeploy. HookDeploy has already answered GoCardless. A 498 from your handler is a failed forward in HookDeploy, not a signal to GoCardless.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which GoCardless treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

GoCardless’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and Webhook-Signature header unchanged, so retries and replays verify like the original delivery. A transformation, or a privacy filter that changes the stored copy used for retries and replays, changes the body, and then the signature won’t match.

GoCardless’s retries, HookDeploy’s retries, and replays can all deliver the same events. Deduplicate on each event’s id.

Set up GoCardless with HookDeploy

  1. In HookDeploy, create an endpoint (for example, GoCardless live) and copy its URL.
  2. On the endpoint’s Security tab, under Network, add GoCardless’s three webhook IP addresses (Starter and above).
  3. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  4. In the GoCardless Dashboard, go to Developers, then Webhooks, and create an endpoint with your HookDeploy URL. Copy its secret.
  5. Send a test webhook from the dashboard, and confirm it appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/gocardless', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.GOCARDLESS_WEBHOOK_SECRET)  // secret used as-is
    .update(req.body)
    .digest('hex');
  const received = req.get('webhook-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(498).send('Invalid signature');  // 498: GoCardless won't retry

  res.sendStatus(204);
  const { events } = JSON.parse(req.body.toString('utf8'));
  for (const event of events) {
    await enqueue({ eventId: event.id, resourceType: event.resource_type, action: event.action, links: event.links });
  }
  // Deduplicate on eventId, then fetch the resource's current state from the API.
});

FAQ

How do I verify a GoCardless webhook?

Compute a hex HMAC-SHA256 of the raw request body using the endpoint's secret, used as-is, and compare it to the Webhook-Signature header. If it doesn't match, return 498.

Why does GoCardless want a 498 response?

A 498 Token Invalid tells GoCardless the signature failed and it shouldn't retry. A 400 or 401 would be retried like any other error, and a 200 would mark a forged request as delivered.

How many times does GoCardless retry?

GoCardless makes 9 delivery attempts in total, one initial attempt and 8 retries at increasing intervals, for any non-2xx response other than 498 or 204. You can also retry manually from the dashboard for 3 months.

Why do GoCardless events arrive out of order?

Delivery order isn't guaranteed, so a confirmed event can arrive before the created event it follows. Fetch the resource from the API when you process an event, and act on its current state.

How do I deduplicate GoCardless webhooks?

Use each event's id inside the events array. The meta.webhook_id identifies a delivery attempt, not an event, so it changes on retries.

Does HookDeploy break GoCardless signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and Webhook-Signature header unchanged, so first deliveries, retries, and replays all verify.

Capture GoCardless webhooks free

Start free