Developer Resources
GoCardless CLI
Installation Testing Webhooks (CLI) About CLI gocardless gocardless analytics gocardless analytics disable gocardless analytics enable gocardless analytics status gocardless cancel gocardless completion gocardless config gocardless config current-session gocardless create gocardless delete gocardless get gocardless get creditor gocardless get customer gocardless get customer_bank_account gocardless get customer_notification gocardless get event gocardless get mandate gocardless get mandate_import gocardless get payer_authorisation gocardless get payment gocardless get payout gocardless get refund gocardless get subscription gocardless get webhook gocardless list gocardless list creditors gocardless list customer_bank_accounts gocardless list customer_notifications gocardless list customers gocardless list events gocardless list mandate_imports gocardless list mandates gocardless list payer_authorisations gocardless list payments gocardless list payouts gocardless list refunds gocardless list subscriptions gocardless list webhooks gocardless listen gocardless login gocardless mcp gocardless mcp add gocardless mcp add claude gocardless mcp add codex gocardless mcp remove gocardless mcp remove claude gocardless mcp remove codex gocardless mcp run gocardless open gocardless trigger gocardless trigger billing_request_fulfilled gocardless trigger billing_request_fulfilled_payment_failed gocardless trigger billing_request_fulfilled_payment_paid_out gocardless trigger billing_request_pending gocardless trigger mandate_activated gocardless trigger mandate_expired gocardless trigger mandate_failed gocardless trigger mandate_pending_submission gocardless trigger mandate_transferred gocardless trigger payment_chargeback_settled gocardless trigger payment_charged_back gocardless trigger payment_confirmed gocardless trigger payment_failed gocardless trigger payment_paid_out gocardless trigger payment_pending_submission gocardless trigger payment_submitted gocardless update gocardless versionResource: Testing Webhooks (CLI)
Testing Webhooks with the CLI
Webhooks allows you to receive real-time notifications from GoCardless when things happen in your merchant's account.
You can use the gc CLI to locally test your webhook integrations. Each event from GoCardless contains an Event object with a link referencing the resource that was modified. This document will explain how the CLI can be used to trigger these events and inspect their output or even forward them to your server's webhook handler.
Listening for events
Use the gocardless CLI to listen for new events
$ gocardless listen
Started listening for new webhooks. Any new webhooks will be printed to your console.Triggering an event
In a different terminal tab, use the trigger CLI command to trigger a mock webhook event. For example, let's trigger a mandate activated event.
$ gocardless trigger mandate_activated
This will trigger a mandate_activated event and create necessary resources in the process ⏳
Event triggered successfully, see dashboard for events 🚀You should see an output similar to the following in your listen tab:
Received event:
{
"action": "active",
"created_at": "2022-02-24T12:49:32.066Z",
"details": {
"cause": "mandate_activated",
"description": "The time window after submission for the banks to refuse a mandate has ended without any errors being received, so this mandate is now active.",
"origin": "gocardless"
},
"id": "EV00QXTDGM5895",
"links": {
"mandate": "MD000K62KEVTEQ"
},
"resource_type": "mandates"
}Forwarding events to your Webhook Handler
The listen command also allows you to forward events as a standard webhook to a live webhook server.
Assuming you have a webhook handler running at the following URL http://localhost:8001/webhook, then you can have the CLI forward the webhook event to it using the --forward flag like:
$ gocardless listen --forward http://localhost:8001/webhookNow events will get forwarded to your webhook URL. Ensure your webhook handler performs all the necessary checks we recommend when handling webhook.
Now, you can test how your integration reacts to different events using the gc CLI.
Next Steps
Handling Webhooks - Staying up to date with Webhooks
Trigger Command Reference - CLI trigger Reference
Listen Command Reference - CLI listen Reference
Check out the List of Command References - CLI Command Reference