SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgocardless-webhooks

gocardless-webhooks

Testing & quality

View repository

Updated 10-15 22:14

About this skill

GoCardless Webhooks

GoCardless is a bank debit / recurring payments platform. It sends webhooks as batches of events (up to 250 per request) in an events array, signed with an HMAC-SHA256 signature in the Webhook-Signature header.

When to Use This Skill

  • How do I receive GoCardless webhooks?
  • How do I verify the GoCardless Webhook-Signature header?
  • Why is my GoCardless webhook signature verification failing?
  • How do I handle payments confirmed/failed, mandates cancelled, or payouts paid events?
  • How do I process the GoCardless events array idempotently?

How GoCardless Signs Webhooks

  • Header: Webhook-Signature — a bare 64-char lowercase hex digest (no X- prefix, no sha256= scheme prefix)
  • Algorithm: HMAC-SHA256 over the raw request body, keyed with the webhook endpoint secret (from your GoCardless Dashboard)
  • Key: use the secret verbatim as a UTF-8 string — do NOT base64-decode it even though it looks base64url-ish; decoding it produces a wrong signature
  • Encoding: lowercase hex string
  • Comparison: timing-safe equality
  • Response: return 204 No Content once the whole batch is accepted; a non-2xx (e.g. 498) marks the delivery failed. GoCardless does not auto-retry — redelivery is manual (POST /webhooks/{id}/actions/retry). Delivery is at-least-once, so keep handlers idempotent on event.id.

(Scheme verified 2026-08 against a live sandbox delivery and the official gocardless-nodejs SDK; GoCardless's prose still doesn't name the algorithm.)

Always verify against the raw body — parsing JSON first and re-serializing will change the bytes and break the signature.

Verification (core)

Use the official gocardless-nodejs SDK where it runs (Node.js). parse() verifies the signature (timing-safe) and returns the events array, throwing InvalidSignatureError when the signature does not match.

// Node.js — official SDK (gocardless-nodejs), req.body is the RAW Buffer
const { parse, InvalidSignatureError } = require('gocardless-nodejs/webhooks');

try {
  const events = parse(
    req.body,                                  // raw body (Buffer/string), NOT parsed JSON
    process.env.GOCARDLESS_WEBHOOK_SECRET,     // webhook endpoint secret
    req.headers['webhook-signature']           // Webhook-Signature header
  );
  // signature valid — process each event, then respond 204
} catch (err) {
  if (err instanceof InvalidSignatureError) {
    // signature mismatch — respond 498 (do not process)
  }
}

For languages without a GoCardless SDK (e.g. Python/FastAPI), verify manually — same algorithm, timing-safe compare:

import hmac, hashlib
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature_header)  # timing-safe

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

GoCardless events combine a resource_type with an action. The most common:

resource_type action Triggered When
payments confirmed Funds confirmed collected from the customer
payments paid_out Payment included in a payout to your bank account
payments failed Payment failed (e.g. insufficient funds)
payments cancelled Payment cancelled before submission
payments charged_back Customer charged the payment back
mandates active Mandate set up and ready to collect
mandates customer_approval_granted Customer authorised the mandate (confirmed live)
mandates cancelled Mandate cancelled (e.g. bank account closed)
mandates failed Mandate setup failed
mandates expired Mandate expired through inactivity
payouts paid Payout sent to your bank account
refunds paid Refund submitted to the customer
refunds failed Refund failed
subscriptions created Subscription created
subscriptions cancelled Subscription cancelled

See overview.md for the full action list per resource type.

Environment Variables

# Webhook endpoint secret from the GoCardless Dashboard (Developers → Webhook endpoints)
GOCARDLESS_WEBHOOK_SECRET=your_webhook_endpoint_secret

Local Development

For local webhook testing, run the Hookdeck CLI via npx — no install required:

npx hookdeck-cli listen 3000 gocardless --path /webhooks/gocardless

No account required. The CLI creates a guest account on first run and provides a local tunnel + web UI for inspecting requests. Use port 8000 for the FastAPI example.

Reference Materials

  • Overview - What GoCardless webhooks are, full event/action list
  • Setup - Create a webhook endpoint and copy the secret
  • Verification - Signature verification details and gotchas

Examples

  • Express Example - Express 5 handler using the GoCardless SDK, with tests
  • Next.js Example - Next.js App Router route using the GoCardless SDK, with tests
  • FastAPI Example - Python FastAPI handler with manual HMAC verification, with tests

Recommended: webhook-handler-patterns

We recommend installing the webhook-handler-patterns skill alongside this one. GoCardless doesn't auto-retry (redelivery is manual), but delivery is at-least-once, so idempotency matters. Key references (open on GitHub):

  • Handler sequence — Verify first, parse second, handle idempotently third
  • Idempotency — Prevent duplicate processing (dedupe on event.id)
  • Error handling — Return codes, logging, dead letter queues
  • Retry logic — Provider retry schedules, backoff patterns

Related Skills