GoCardless Connection Webhook

POST

webhooks

gocardless

{connID}

GoCardless webhook receiver (per-connection, BYO)

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

import requests

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

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/{connID}', 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/{connID}",
  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/{connID}"

	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/{connID}")
  .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/{connID}")

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>"
  }
}

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

Per-connection variant of the GoCardless webhook receiver for workspaces that connected their own GoCardless account with Connect a Gateway. The batch is verified with that connection’s own webhook secret (resolved from connID) before any event is trusted. Payment events are bound to the connection’s workspace; mandate events are not (see below). Event handling is otherwise identical to the platform receiver.

Each connection has its own URL. Read webhook_path from List Gateway Connections (for example /webhooks/gocardless/{connID}), append it to https://api.recurso.dev, and register that URL in the GoCardless Dashboard under Developers > Webhook endpoints using the webhook_secret you supplied when connecting, or set later with Set Gateway Webhook Secret. A connection without a webhook secret cannot verify deliveries and rejects them.

Parameters

Parameter	Type	Required	Description
`connID`	string (UUID, path)	Yes	The workspace’s GoCardless gateway-connection id.
`Webhook-Signature`	string (header)	Yes	HMAC-SHA256 hex signature of the raw request body, computed with the connection’s 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. A payment event whose invoice belongs to a different workspace than the connection is ignored, never applied. billing_requests and mandates events are resolved by their GoCardless id alone and are not checked against the connection’s workspace.

Example Request

GoCardless sends a POST request with a batch of events:

curl -X POST https://api.recurso.dev/webhooks/gocardless/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Content-Type: application/json" \
  -H "Webhook-Signature: 3f1a9c0e7b2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b" \
  -d '{
    "events": [
      {
        "id": "EV0123456789ABCD",
        "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, a payment for another workspace’s invoice). 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": 1
}

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`	`connID` in the path is not a UUID	Use the connection’s `webhook_path` from List Gateway Connections
`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 under this connection’s secret	Make sure the secret registered in GoCardless matches the connection’s `webhook_secret`
`404`	`not_found`	No active GoCardless connection has this id (a missing, disconnected, or non-GoCardless connection all return 404)	Reconnect the gateway and register the new `webhook_path`
`503`	`internal_error`	The connection has no webhook secret (the receiver fails closed), per-connection webhooks are not configured on the API, or the inbound-webhook dedup store is unavailable	Store the secret with Set Gateway Webhook Secret (the connection id and `webhook_path` stay the same); 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.

Path Parameters

connID

string<uuid>

required

The tenant's GoCardless gateway-connection id.

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 (per-connection, BYO)

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

import requests

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

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/{connID}', 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/{connID}",
  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/{connID}"

	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/{connID}")
  .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/{connID}")

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>"
  }
}

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

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

GoCardless Connection Webhook

Parameters

Request Body

Example Request

Response

Fields

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Parameters

​Request Body

​Example Request

​Response

​Fields

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Parameters

Request Body

Example Request

Response

Fields

Errors