Webhooks

Learn how to use post-purchase webhooks to trigger events on other applications

Webhooks are a very useful integration option, that you can use to let other webapps know when a purchase has completed in Trolley.

How it works

Once a Trolley payment has been processed and the charge is complete (and verified by Stripe), Trolley will execute any webhook.

(Notably, if the charge fails then the webhook is not executed and the customer remains on the Payment screen in Trolley)

What Trolley does

Trolley executes an HTTP POST request to the URL you specify.

The request will be sent with Content Type application/json and the request body contains the paying customer's email address and the payment reference.

The body content looks like this:

{
  "email" : "test@example.com"
  "reference" : "ABC123"
}

What you need to do

Webhook option

All you need to do is supply a URL to an HTTP endpoint.

Simply go to the Trolley dashboard and edit your Product.

Scroll down, and enter a valid URL into the Webhook field.

This URL should point to an HTTP endpoint that you control, which will receive the webhook call.

It should accept a POST request with Content Type application/json and should return a status code 200.

Note that while Trolley will capture and log errors internally for later analysis, if your webhook returns a status code other than 200 there will be no user feedback in the user interface.

You should account for error scenarios in your server code.

Simulating a webhook request

You can, of course, test the webhook functionality by issuing payments for a Product with a Webhook defined.

You can also simulate the request that Trolley will send as follows:

curl -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}' \
  https://my-domain.com/my-path

Authentication

Trolley will respect all standard URLs, so you can use HTTP Basic authentication to add security to your webhook POST (please make sure that your webhook is served over TLS)

Here's an example: