Stay up to date with webhooks

Staying up-to-date with webhooks

A webhook is a request that GoCardless sends to your server to alert you of an event. Adding support for webhooks allows you to receive real-time notifications from GoCardless when things happen in your account, so you can take automated actions in response, for example:

When a payment fails due to lack of funds, retry it automatically
When a customer cancels their mandate with the bank, suspend their account
When a customer’s subscription generates a new payment, you can record that payment against their account

Create a webhook endpoint

To start receiving webhooks, you’ll need to add a webhook endpoint from your Dashboard here.

Simply enter the HTTPS URL from earlier and add on the path where your webhook handler will be available, give your endpoint a name, and then click “Create webhook endpoint”. Next, click on your new endpoint in the list and copy the secret to your clipboard.

Build a webhook handler

Let’s get started by building our first webhook handler. Webhooks are HTTP POST requests made to the URL you provided, with a JSON body. See an example below.

POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 78e3507f61f141046969c73653402cb50b714f04322da04d766ee0f6d2afe65f

{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-04T12:00:00.000Z",
      "action": "cancelled",
      "resource_type": "mandates",
      "links": {
        "mandate": "MD123",
        "organisation": "OR123"
      },
      "details": {
        "origin": "bank",
        "cause": "bank_account_disabled",
        "description": "Your customer closed their bank account.",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      }
    }
  ]
}

Secure your webhooks

The first step to take when you receive a webhook is to check its signature - this makes sure that is genuinely from GoCardless and hasn’t been forged. A signature is provided in the Webhook-Signature header of the request. We just need to compute the signature ourselves using the POSTed JSON and the webhook endpoint’s secret (which we copied earlier), and compare it to the one in the header.

If they match, the webhook is genuine, because only you and GoCardless know the secret. It’s important that you keep the secret safe, and change it periodically using the Dashboard.

We can verify the signature like this:

<?php
// We recommend storing your webhook endpoint secret in an environment variable
// for security
$webhook_endpoint_secret = getenv("GOCARDLESS_WEBHOOK_ENDPOINT_SECRET");
$request_body = file_get_contents('php://input');

$headers = array_change_key_case(getallheaders(), CASE_LOWER);
$signature_header = $headers["webhook-signature"];

try {
    $events = \GoCardlessPro\Webhook::parse($request_body,
                                            $signature_header,
                                            $webhook_endpoint_secret);

    // Process the events...

    header("HTTP/1.1 204 No Content");
} catch(\GoCardlessPro\Core\Exception\InvalidSignatureException $e) {
    header("HTTP/1.1 498 Invalid Token");
}

Processing events

A webhook can contain multiple events, and each has a resource_type (telling us what kind of resource the event is for, for example, “payments” or “mandates”), an action (telling us what happened to the resource, for example, the cancelled action for a mandate) and details (specifying why the event happened).

You can see a full list of the possible combinations in the reference docs.

As an example, we’ll write a handler for when a mandate is cancelled:

<?php
function process_mandate_event($event)
{
    switch ($event->action) {
        case "cancelled":
            print("Mandate " . $event->links->mandate . " has been cancelled!\n");

            // You should keep some kind of record of what events have been processed
            // to avoid double-processing
            //
            // $event = Event::where("gocardless_id", $event->id)->first();

            // You should perform processing steps asynchronously to avoid timing out if
            // you receive many events at once. To do this, you could use a queueing
            // system like Beanstalkd
            //
            // http://george.webb.uno/posts/sending-php-email-with-mandrill-and-beanstalkd
            //
            // Once you've performed the actions you want to perform for an event, you
            // should make a record to avoid accidentally processing the same one twice.
            CancelServiceAndNotifyCustomer::performAsynchronously($event->links->mandate);
            break;
        default:
            print("Don't know how to process a mandate " . $event->action . " event\n");
            break;
    }
}

// We recommend storing your webhook endpoint secret in an environment variable
// for security
$webhook_endpoint_secret = getenv("GOCARDLESS_WEBHOOK_ENDPOINT_SECRET");
$request_body = file_get_contents('php://input');

$headers = getallheaders();
$signature_header = $headers["Webhook-Signature"];

try {
    $events = \GoCardlessPro\Webhook::parse($request_body,
                                            $signature_header,
                                            $webhook_endpoint_secret);

    foreach ($events as $event) {
        print("Processing event " . $event->id . "\n");

        switch ($event->resource_type) {
            case "mandates":
                process_mandate_event($event);
                break;
            default:
                print("Don't know how to process an event with resource_type " . $event->resource_type . "\n");
                break;
        }
    }

    header("HTTP/1.1 200 OK");
} catch(\GoCardlessPro\Core\Exception\InvalidSignatureException $e) {
    header("HTTP/1.1 498 Invalid Token");
}

Send a test webhook again, just like the one you sent before, and then click on it in the list. You’ll see a response at the bottom like this:

Processing event EVTEST8XP9DCPK
Mandate index_ID_123 has been cancelled!

We’ll send webhooks exactly like this when real events happen in your account.

You can add support for as many differ resource_types and actions as you like, and make use of all of the other data we give you with events.

Test your webhook handler

Using the Dashboard

In the Dashboard, the “Send test webhook” functionality makes it easy to start experimenting with webhooks. Select the webhook endpoint you created earlier, set the Resource type of mandates and the action to cancelled. You can set the cause and event details however you like. Then, click “Send test webhook”.

Using the GC CLI Sandbox

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. The CLI can be used to trigger these events and inspect their output or even forward them to your server's webhook handler.

Using the Scenario Simulator Sandbox

In the sandbox environment, we provide scenario simulators that allow you to manually trigger certain cases so you can test how your integration responds. These are available in the Developer section of the dashboard and through the API.

Using TLS client authentication

Using TLS enables us to encrypt data in transit. However, additional security can be achieved by using client authentication in addition to server authentication.

Client authentication adds an extra check in the TLS handshake to validate that the client is authorised to access the endpoint. In this case, it enables you to be certain that it is GoCardless making a request to your webhook endpoint, and not (for example) a malicious entity attempting to spoof GoCardless.

To authorise GoCardless to send webhooks, you need to provide a valid certificate and private key issued by your certificate authority. In practice, this can be a self-signed certificate, and useful instructions for generating certificates can be found in the CoreOS documentation, using Cloudflare’s cfssl toolkit. Note that for the time being, we only support RSA keypairs. We recommend setting a long lifetime for the certificate to avoid unnecessary management overhead.

Once generated, the certificate and key must be entered into the webhook endpoint form in the developers section of the GoCardless dashboard. Both certificate and key must be provided in base64-encoded PEM format.

All subsequent requests from the webhook system will be client-authenticated.

The main disadvantage to using this feature is the overhead of creating, renewing and otherwise managing client certificates. It is up to you to balance this overhead against the additional security risk.