Webhook notifications

Understand how to interact with Vyne webhook notifications

When the status of a payment or refund is updated, Vyne will send a digitally signed POST request to the specified callback URL. See webhooks in action when using Payment status updates or Refund status updates.

🚧

Be aware

  1. Callbacks will timeout after 1 minute. If Vyne is unable to establish a connection, or does not receive a response after 1 minute, the request will timeout.
  2. In order to receive webhook notifications from from Vyne's servers, you must whitelist the relevant IP addresses listed here.

Verifying integrity

Every webhook notification sent by Vyne is digitally signed using public key cryptography, also known as asymmetric cryptography, and will allow the merchant verify the origin and the integrity of the message.

Example response

--header 'x-signature=h4DnIgww/Qw0NhMFlzgQuLKpvhVgJGm5ZSImO7wh7MewUX3AJYa06fwh9naN1Zp7h9OopRbVR3oY8L0PzDmirXyX1QM3eRZIkSjAZs+S9vx7D2ETH0WGk3ByJ28i3j6Q3Be3G5PEx91llVgTsOyYTdKVykzh/b8azI+5fr45PMe6mOKVjb8hoBsMJP9n+jQWQ8NnkR9h4iCxxqULFsY+oXu08dFFMPfnyc2Lp7rA66kLZVU7w4XS3rrNxoWV65Z75lvB8wAefWkR9KdFE8kWdZpAqdG+nC78EEZOo3fMoW+RuNKP57rw0yjC0Xmh8fActzTVyKcBlhum+/fTBc8rCbeoFKoHBiXQ+mcTKTdTveVEe2P95jtet6C2AMI0grRo7N45kMPT2IhyFxe4WUtafkpkJhTCu65QliGlQwKnebCQYB4uQUmvTQ8vli8FKjomeGis4KYOkQMA1YAatVF00IThbVVKO3QafVGUfn3Sue6EdNPT8UW8DiQ2UPsAYCI8N+M0YyebQZ48NqAv6Rp0Kz/srxiJc7YiWhLIgmoFe5Kfz+HWrIIZknH66HRhK3AFYocSliWtOH9p6YwaDNZ/M7giW7zjNpjWyRq7uoPLFD9OYZgaC+4vIreL3KTx/eCVHx0yqNajVSYAuMExwrPxoctklGAjuWHEFIRtm6wXqE0='
--header 'x-signature-keyId=718c7272-4e33-466b-8ad8-28fa2c95193f'

Parameter

Description

x-signature

A signature generated by Vyne which will allow the merchant verify the origin and the integrity of the message. The signature is base64 encoded string with a length of 684 characters

x-signature-keyId

Key ID of the public key which can be used to verify the signature. It’s a 36 character string displayed in five groups separated by hyphens in the following format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

There are two keys which are mathematically linked: one private and one public key.

  • The private key is used by the Vyne webhook to generate a signature.
  • The public key is available publicly and can be used to confirm if the signature is valid.

Role

Responsibility

Signature generation (by Vyne)

A hash is calculated from the notification body which is then encrypted with the private key.

Signature verification (by the merchant)

The signature is decrypted with the public key and it must match with the computed hash of the notification body. If the outcomes don't match, the notification body has either been tampered with or the signature was created with a private key that doesn't correspond to the public key presented by the signer.

Merchants are responsible for validating the origin and the integrity of every message. In order to validate the message, you'll need:

  1. The body of the notification - make sure that you have access to the raw message payload, any modification or formatting of the payload will fail validation of the signature.
  2. KeyId from the x-signature-keyId response header, and the corresponding public key.
  3. Signature from the x-signature response header
  4. Signing algorithm SHA256withRSA

📘

Helpful to know

The latest API keys can be found at the relevant base URL + /api/keys/.

The /api/keys/ endpoint can return multiple public keys in JWKS format, therefore the key with ID corresponding to the x-signature-keyId response header should be used. After the right key is identified, an RSA public key should be constructed from the JWK

In order to check the integrity of the message, the signature (x-signature header) must be decrypted with the public key and the decrypted value must match the hash of the body. Most languages provide support to do this without an external library.

For example, Java/Kotlin uses the Signature class.

val signature: Signature = Signature.getInstance("SHA256withRSA")
signature.initVerify(publicKey)
signature.update(notificationBody.encodeToByteArray())
 
if (signature.verify(Base64.getDecoder().decode(signatureHeader))) {
    //Signature check passed
} else {
    //Signature check failed
}

🚧

Be aware

  1. The existing structure and fields won’t be modified or removed, however Vyne might extend the structure with new fields, so keep this in mind when configuring your parser.
  2. We recommend verifying the integrity of messages using the above outlined methods every time. If the signature check fails, it could be for one of two reasons:
  • The wrong public key was used to check the signature. Make sure that the key used corresponds with the one in x-signature-keyId response header
  • The message was tampered with and should not be trusted or wasn’t sent by Vyne.

Did this page help you?