Order Webhooks

This guide explains how to implement and test the webhooks receiver and configure webhooks on the Worldpay website.

Webhooks allow you to be notified of order status changes. Once you have set up a webhook, Worldpay will send an HTTP request to your server whenever the state of one of your orders changes. The full set of order states is documented in the ordersAPI Referencepage.

Implementing the Webhooks Receiver

The code example below shows you what a Worldpay webhook looks like:

  "merchantId" : "c673e5e13-df89-34e5-a6f3-7584903d4f34",
  "notificationEventType" : "ORDER_STATE_CHANGE", 
  "adminCode" : "MERCHANT_ADMIN_CODE",
  "merchantCode" : "MERCHANT_CODE", 
  "orderCode" : "worldpay-order-code", 
  "paymentStatus" : "SUCCESS", 
  "environment" : "LIVE"

The webhook will be a HTTPS POST request with body content similar to the following.

The order code is the same as that used when setting up the order API. The paymentStatus shows the current state of the order. The environment will either show as TEST or LIVE. Please note that the field range may be occasionally increased, so your server should not assume that this will be the full content.

When your endpoint accepts the notification, the only status code which will be recognised by Worldpay as a valid request response is 200 (OK). Any other status code will be interpreted as a failed delivery, in which case the notification will be re-tried.

Webhook notifications which do not receive a 200 status code in the response will be redelivered. The second delivery will happen immediately. If this also fails, then six more delayed deliveries will be attempted after one hour, two hours, four hours, eight hours, 16 hours and 24 hours.

If all of these attempts fail then delivery is abandoned for that notification. This redelivery schedule is applied individually to each notification, so failures for one notification will not affect any others being accepted by your endpoint.

Configuring webhooks on the Worldpay website

Webhook notifications can be enabled by entering your service URL on the Webhooks Settings page.

Testing the Webhooks Receiver

After you set up your webhook, you can generate a test webhook from the Webhooks Settings page by clicking on test webhook. We will send a dummy notification to your service, and also show you the results on the screen. You can choose which paymentStatus to use in the UI.

The dummy content will be as follows:

   "id": "c673e5e13-df89-34e5-a6f3-7584903d4f34",
   "webhookId": "c63d4e10-ba85-11e3-a4e2-0800200c9a66",
   "orderCode": "dummy_db17f550-ba4f-11e3-a5e2-0800200c9a66",
   "paymentStatus": "SUCCESS",
   "environment": "TEST"

The order code is prefixed with dummy_ and contains a randomly generated webhook. The paymentStatus mirrors the UI selection, while environment will always show as TEST.

The response status code returned by your endpoint is also displayed on the page, so this can be checked against your own server logs. Note that test notifications will not be redelivered if your endpoint returns a non-200 status code.

You can generate your own test webhook by using the following cURL command:

curl https://your-server-name/your-webhook-endpoint 
    -H "Content-type: application/json" 
    -X POST 
    -d '{ 
        "id" : "8da9ad40-c580-11e3-9c1a-0800200c9a66", 
        "webhookId" : "c63d4e10-ba85-11e3-a4e2-0800200c9a66", 
        "orderCode" : "worldpay-order-code", 
        "paymentStatus" : "SUCCESS", 
        "environment" : "TEST"