Events allow 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, record that payment against their account
There are two ways to receive Event information:
Webhooks - A webhook is a request that GoCardless sends to your server to alert you of an event.
The Events endpoint - You can list events directly from the Events endpoint if you prefer to pull the information yourself. This may be preferable if you’re going to be processing large volumes of events.
Processing Events using webhooks
Making localhost accessible to the internet with ngrok
To start experimenting with webhooks, your code will need to be accessible from the internet so GoCardless can reach it with HTTP requests. If you’re working locally, the easiest way to do this is with ngrok.
Download it and follow the instructions on the page to install it (you’ll need to unzip the archive, and then make the ngrok binary available in your PATH).
Now, just run ngrok http <port>
, where <port> is the port where your web server is running (for example ngrok http 8000
if you’re running on port 8000).
You’ll see two links that forward to localhost:8000. Select the URL that starts with https, and copy it to your clipboard.
In the sandbox, you can use an HTTP URL for your webhooks, but to go live, the endpoint must be HTTPS secured.
Adding a webhook URL in the GoCardless Dashboard
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.
Building a webhook handler
Webhooks are HTTP POST requests made to the URL you provided, with a JSON body.
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.
Once the signature is authenticated, you can then send a 2xx response before processing the JSON payload.
Please note, that if you don’t respond with a 2xx response within 10 seconds, the webhook will fail and we will then retry the webhook at the intervals mentioned here. It’s therefore important to process the webhooks asynchronously to avoid timing out if you receive many events at once. I.e. send a 2xx response before processing the webhook.
Once you've performed the actions you want to perform for an event, we’d also suggest making a record to avoid accidentally processing the same one twice.
For detailed code samples on how to check the signature, please refer to the link here.
Testing your webhook handler
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”.
Now, refresh the page. Usually, the webhook will appear right away, but sometimes you might have to refresh a few times. We’ll make a request to your endpoint, and your webhook will appear in the list - click on it. If everything’s working, you’ll see a response code of 200 OK.
Webhook retries / failures
Webhooks can fail to be sent due to a number of reasons, such as:
- Timeouts - We didn’t receive a 2xx response within 10 seconds of sending the webhook.
- Unauthorised access - Server authorisation is required, however, invalid authentication was provided.
- The request was redirected - We won’t follow any HTTP redirects, therefore we treat these as webhook failures.
If a webhook fails, we will retry the webhook up to 8 times at increasing intervals e.g. 1 minute, 2 minutes, 10 minutes etc.
Processing the Events within webhooks
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 and an example event handler here.
You can add support for as many different source_types
and actions as you like, and make use of all of the other data we give you with events.
Triggering webhooks
When you’re building your integration, you’ll want to receive realistic webhooks so you can test how your integration responds.
You can trigger webhooks using our scenario simulators, or with the “Send test webhook” tool - just click “Send test webhook” on your “Developers” page in the dashboard.
Before you can use the “Send test webhook” tool, you’ll need to have a webhook endpoint set up. Click “Create" then “Webhook endpoints” on the “Developers” page in your dashboard. If you’ve created any apps, their webhook endpoints will also be available.
You’ll then be able to customise your webhook. First, choose your webhook endpoints, and then set the resource type, action, cause, event details and associated ID.
In your code, you’re likely to use the ID to locate records in your database and take relevant actions based on your webhook.
Click “Send test webhook”, and we’ll send the webhook to your chosen endpoint, usually within a few seconds.
Refresh the page, and the webhook you’ve just sent will appear in your list of webhooks.
Click on a webhook, and you can see the full request, plus your response. This is really useful for debugging purposes.
You can resend a webhook you’ve already sent by choosing it from the list, then clicking “Retry” in the top-right hand corner.
Processing Events using the Events endpoint
An alternative to webhooks is to pull the information directly from the Events endpoint.
This is a popular alternative that provides more control over when you process the events and removes the complexities surrounding webhook failures / retries.
This would involve making a call to list events at certain times throughout the day, using the created_at[gt] parameter to list events created since your last poll.
You can also choose to pull / handle specific events by using any of the parameters listed here. E.g. to just receive mandate cancelled events, you would send a request similar to the following:
GET https://api-sandbox.gocardless.com/events?action=cancelled&resource_type=mandate HTTP/1.1
It's also worth noting that the majority of events are created when we receive (8-11am BST) and send (3-6pm BST) reports to the bank. Therefore we usually suggest querying the endpoint around midday, then in the evening and any other periods you wish.