Results for

icon-search-large No search results yet
Enter your search query above

An incoming webhooks message contains the following information:

  1. An HTTP header which contains signature related information
  2. 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 Ingenico specific headers that webhooks uses:

HTTP headerDescription
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 fieldDescription
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.

  1. payment
  2. refund
  3. payout
  4. token

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
    }
  }
}