Webhooks event structure

An incoming webhooks message contains the following information:

An HTTP header which contains signature related information
A HTTP body containing a JSON message which consists of two parts:
1. Event metadata
2. The object the event occurred on at the time the event took place.

HTTP headers

There are two Worldline specific headers that webhooks uses:

HTTP header	Description
X-GCS-Signature	The HMAC-SHA256 signature of the HTTP body. Our SDKs and eCommerce plugins can validate the signature for you, but you can do this manually as well if needed.
X-GCS-KeyId	The id of the key that was used to create the signature.

Event metadata

We'll explain all the metadata fields in the JSON using the example below.

{
  "apiVersion": "v1",
  "id": "97a4fcdf-9a08-4a59-a0c0-69bfd7e1d59d",
  "created": "2017-09-14T17:14:39.688+0200",
  "merchantId": "20000",
  "type": "payment.created",
  ... // the object goes here
}

JSON field	Description
apiVersion	The version of the REST API that is used for the structure of the object.
id	The unique id of this event. You should use this id to verify that you did not already receive this event.
created	The date and time that the event occured in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format
merchantId	The id of the merchant the event occurred on.
type	One of the event names as listed on our webhooks event types page. Each type is of the following format: object.event, e.g. "payment.created" or "refund.captured".

Event object

The name of the event object field and the structure of its value depends on the event type. The structure is identical to that of the response of the REST API calls that correspond to the "object" part of the event type. The list below shows the four object types that we currently support and links to the REST API endpoints that define the structure of the field value.

Below is an example of a payment event. Keep in mind that the structure of this payment response depends on the specific payment. The SDKs can automatically unmarshall the JSON and provide an object for you to work with.

{
  ..., // the metadata goes here
  "payment": {
    "id": "12345",
    "paymentOutput": {
      "amountOfMoney": {
        "amount": 1000,
        "currencyCode": "EUR"
      },
      "references": {
        "paymentReference": "200001681810"
      },
      "paymentMethod": "bankTransfer",
      "bankTransferPaymentMethodSpecificOutput": {
        "paymentProductId": 11
      }
    },
    "status": "CREATED",
    "statusOutput": {
      "isCancellable": false,
      "statusCategory": "CREATED",
      "statusCode": 0,
      "statusCodeChangeDateTime": "20170901170000",
      "isAuthorized": false
    }
  }
}