GoCardless Webhook

POST

webhooks

gocardless

GoCardless webhook receiver (platform account)

curl --request POST \
  --url https://billing.example.com/webhooks/gocardless \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Webhook-Signature: <webhook-signature>' \
  --data '{}'

import requests

url = "https://billing.example.com/webhooks/gocardless"

payload = {}
headers = {
    "Webhook-Signature": "<webhook-signature>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Webhook-Signature': '<webhook-signature>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://billing.example.com/webhooks/gocardless', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/webhooks/gocardless",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "Webhook-Signature: <webhook-signature>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/webhooks/gocardless"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Webhook-Signature", "<webhook-signature>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/webhooks/gocardless")
  .header("Webhook-Signature", "<webhook-signature>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/webhooks/gocardless")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Webhook-Signature"] = '<webhook-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "status": "ok",
  "processed": 123
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

This endpoint receives webhook deliveries from GoCardless for the platform’s own GoCardless account. Unlike the Razorpay and Stripe receivers, each GoCardless delivery batches many events; Recurso verifies the whole body once and then processes (and deduplicates) each event individually. Workspaces that connected their own GoCardless account use the per-connection receiver instead.

This endpoint verifies the delivery using the platform’s GOCARDLESS_WEBHOOK_SECRET. Configure the URL https://api.recurso.dev/webhooks/gocardless in the GoCardless Dashboard under Developers > Webhook endpoints with the same secret. Without a registered webhook, authorized mandates stay created and never debit.

Parameters

Parameter	Type	Required	Description
`Webhook-Signature`	string (header)	Yes	HMAC-SHA256 hex signature of the raw request body, computed with the webhook secret.

Request Body

The raw GoCardless events payload: an object with an events array. Each event is handled by its resource_type and action:

Event	Effect
`billing_requests` / `fulfilled`	Activates the local mandate and stores the real `MD...` mandate id that future debits reference.
`mandates` / any action	Keeps the local mandate status in sync with GoCardless.
`payments` / `confirmed`, `paid_out`	Settles the invoice that references this payment (`open` → `paid`) and records the dunning success.
`payments` / `failed`, `cancelled`	No state change; the invoice stays `open` and dunning picks it up.
`payments` / `charged_back`, `late_failure`	Reverses a settled payment: the invoice reopens (`paid` → `past_due`) and the settlement cash leg is reversed in the ledger.

Any other event is acknowledged and ignored.

Example Request

GoCardless sends a POST request with a batch of events:

curl -X POST https://api.recurso.dev/webhooks/gocardless \
  -H "Content-Type: application/json" \
  -H "Webhook-Signature: 3f1a9c0e7b2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b" \
  -d '{
    "events": [
      {
        "id": "EV0123456789ABCD",
        "resource_type": "billing_requests",
        "action": "fulfilled",
        "links": {
          "billing_request": "BRQ0123456789ABCD",
          "mandate_request_mandate": "MD0123456789ABCD"
        }
      },
      {
        "id": "EV0123456789ABCE",
        "resource_type": "payments",
        "action": "confirmed",
        "links": {
          "payment": "PM0123456789ABCD"
        }
      }
    ]
  }'

Response

Returns 200 OK once the batch has been processed. processed counts every event that was accepted on this delivery, including the ones acknowledged and ignored (an unknown resource_type, a billing_requests action other than fulfilled, a payment id that no invoice references). It is not a count of side effects. Events already recorded by an earlier delivery are skipped silently and not counted, and an event whose handler returned an error is not counted either.

{
  "status": "ok",
  "processed": 2
}

When mandate handling is not configured on the API, the batch is acknowledged without processing:

{
  "status": "ignored"
}

Fields

Field	Type	Description
`status`	string	`ok` when the batch was processed, `ignored` when mandate handling is not configured.
`processed`	integer	Number of events accepted on this delivery: the events in the batch minus duplicates minus events whose handler returned an error. Ignored events count. Present only when `status` is `ok`.

An event whose handler returns an error (for example, a transient database error while looking up the invoice for a payment id) is logged and left unrecorded rather than failing the batch, so the next redelivery retries it. A payment id that simply matches no invoice is not an error: it is acknowledged, counted in processed, and recorded, so it is never retried. Per-event deduplication skips the events that already completed, so nothing is processed twice.

Errors

Status	Code	When	Fix
`400`	`validation_failed`	Request body could not be read, or is not valid JSON	Check the delivery in the GoCardless Dashboard; Recurso expects the raw events payload
`401`	`unauthorized`	`Webhook-Signature` does not match the HMAC-SHA256 of the raw body	Make sure the secret in the GoCardless webhook endpoint matches `GOCARDLESS_WEBHOOK_SECRET`
`503`	`internal_error`	`GOCARDLESS_WEBHOOK_SECRET` is not set on the API (the receiver fails closed), or the inbound-webhook dedup store is unavailable	Self-hosted: set `GOCARDLESS_WEBHOOK_SECRET` and restart; otherwise let GoCardless retry

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Headers

Webhook-Signature

string

required

HMAC-SHA256 hex signature of the raw request body.

Body

application/json

Raw GoCardless events payload.

Response

Batch processed (individual events may be ignored).

status

enum<string>

Available options:

ok,

ignored

processed

integer

GoCardless webhook receiver (platform account)

curl --request POST \
  --url https://billing.example.com/webhooks/gocardless \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Webhook-Signature: <webhook-signature>' \
  --data '{}'

import requests

url = "https://billing.example.com/webhooks/gocardless"

payload = {}
headers = {
    "Webhook-Signature": "<webhook-signature>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Webhook-Signature': '<webhook-signature>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://billing.example.com/webhooks/gocardless', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/webhooks/gocardless",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "Webhook-Signature: <webhook-signature>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/webhooks/gocardless"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Webhook-Signature", "<webhook-signature>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/webhooks/gocardless")
  .header("Webhook-Signature", "<webhook-signature>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/webhooks/gocardless")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Webhook-Signature"] = '<webhook-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "status": "ok",
  "processed": 123
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Parameters

Request Body

Example Request

Response

Fields

Errors

Authorizations

Headers

Body

Response

​Parameters

​Request Body

​Example Request

​Response

​Fields

​Errors

Authorizations

Headers

Body

Response

Parameters

Request Body

Example Request

Response

Fields

Errors