Resource: 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 gc CLI to listen for new events

$ gc 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.

$ gc 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:

$ gc listen --forward http://localhost:8001/webhook

Now 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

Need help?

Connect as a partner