Skip to main content

Webhooks

With webhooks your system can subscribe to updates from Walley. By registrating one or many URLs at Walley, we can call it when we need to update you with new information.

Use Webhooks​

Webhooks is in preview

Currently the webhook functionality is in preview mode and may change before general availability

Step 1. Expose an HTTPS endpoint​

To receive webhooks you are required to have an HTTPS endpoint.

Endpoint requirements

  • Must listen to HTTP POST method
  • Must be able to receive JSON body
  • Must support HTTPS with TSL 1.2 or 1.3

Endpoint recommendations

  • Basic authentication with username or password
  • Support for HTTP2
  • Validating the Walley-Signature header with HMAC key

Step 2. Accept webhooks​

When you receive a webhook request you are required to respond with a http status code in the 2xx series.

Step 3. Configure webhooks in Walley MerchantHub​

Not available right now.

Step 4. Test and enable for Production​

Not available right now.

Structure​

You will receive a request body formated in JSON which will contain a type property with the name of the event, the timestamp when the event occured and a payload that can be diffrent for each event.

{
"type": string,
"timestamp": date,
"payload": object
}

Events​

Events are grouped into these categories:

Headers​

These headers will be included in the webhook requests

KeyDescription
User-AgentStandard http header the value would be something like, Walleybot 0.1 (+https://dev.walleypay.com)
Walley-CorrelationIdThe id of the request that triggered the webhook request, if you have issues with any request please provide this value in the support ticket.
Walley-TimestampUNIX timestamp when this event occured, this is used for HMAC validation see below.
Walley-SignatureComputed signature from Walley, this is used for HMAC validation see below.
Walley-LiveTrue or False, this is used to know if the request to the webhook is made from Walleys production or a test triggered from the MerchantHub. True indicates production data.

Verifying the request with HMAC​

When you set up a webhook, you'll get a HMAC key for it. You can use this key to check that requests you retrieve originates from Walley by using the follow method:

  1. Retrive the request header Walley-Timestamp
  2. Concatenate the version number, the timestamp, and the body of the request to form a basestring. Use a semicolon as the delimiter between the three elements. The version number right now is always v0. Exampel v0:{Timestamp};{Body}
  3. Hash the string described above with the HMAC SHA256 implementation of you systems platform, using the HMAC secret for the webhook.
  4. Compare the computed signature with the request header Walley-Signature