Webhooks

Define webhook rules to your server. The callback URL will receive a POST request with the related object's (e.g. Purchase for purchase.* webhooks) data in body when any of the events is configured to listen for are triggered. The payload object will additionally include an "event_type" field to indicate which event type triggered the webhook and "status" to indicate failure or success of the transaction.

The webhooks can be defined in the developer section of the client account.

Note that, as well as with the rest of dataset, test and live Webhooks are separate; test webhooks will not handle events caused by live Purchases, and vice-versa.

Webhook Authorization

Payloads are signed using asymmetric A.K.A. public-key cryptography to guarantee the authenticity of delivered callbacks. Each callback delivery request includes an X-Signature header field. This field contains a base64-encoded RSA PKCS#1 v1.5 signature of the SHA256 digest of the request body buffer.

You can obtain the public key for Webhook authentication from Webhook.public_key of the corresponding Webhook.

You can obtain the public key for success callback authentication from GET {base_url}/api/v1/public_key/

Please note the provider is not responsible for any financial losses incurred due to not implementing payload signature verification.

See below sample

PHP

<?php
$data = "Hello World";

$signature = 'ktRxi//UUzVK8Pi5ICRSs5nCaK2g5Op+BM2mq4BK6zrb+A2392fiuFBoNj4yBWLfJxzzl1IwgVgQbjjrnbJ3i4kpYTZQ1nG82zpD7SAiF6qWq06YHR5Hrp0uvkiCKHt6pDYkXsCIph8VQqp61uplv3gifTtMRR1BGXwcxfWdrTheiFGWPnlijFaoMgLOG5CVfQAif9E7zx2ybDYtu2mMnxUWAld5bxNZXMKG87NGQ42tLaUE5OYv5yJz0kZZPZFZ5d0neGLAdm+Njf5zWlOw==';

$publicKey = '-----BEGIN CERTIFICATE-----
MIIFMDCCBBigAwIBAgISA8MYezqjKnHZa+83lO64HqQoMA0GCSqGSIb3DQEBCwUA
MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD
EwJSMzAeFw0yMzA2MTYxNjE0MjdaFw0yMzA5MTQxNjE0MjZaMB4xHDAaBgNVBAMT
E3BheW1lbnRzLmFmcml2ci5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
AoIBAQDCFjhZsB7yR669TQ7mxWo9w7ajiT8Z3VZUrWSm0SKmsoxgQ1oDb1yDWIDU
fNCGQvaoRcxBfB+g9D3rhiGtX5oi8FhSFSEuNFXRN3kTVm8vRmfFdY45sjBdtF0j
8RjGwskqSzCzciXfSLoeKoLubUMcCTmUC9FLkwDqkQHedswcYG5AalvBqT7eqtBe
zip1+tVdZSVq79m5EJw98ccLF42cinkoqK76Mg2uss0mNuvpSxFN7gn/0XhaLl5U
5F2kwQr3qsijWLHqOm2cHyGOeiVScbJexvhnVMlJMEblHU/x/K6gZTCj4+O7KDgg
Gh3LHmZJ9sAtRudvM/16jGxIGoknAgMBAAGjggJSMIICTjAOBgNVHQ8BAf8EBAMC
BaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAw
HQYDVR0OBBYEFMJallKq+V5W8oqJPkmioUIvRMKGMB8GA1UdIwQYMBaAFBQusxe3
WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0
cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5j
ci5vcmcvMFsGA1UdEQRUMFKCE3BheW1lbnRzLmFmcml2ci5jb22CDnNydi5hZnJp
dnIuY29tghd3d3cucGF5bWVudHMuYWZyaXZyLmNvbYISd3d3LnNydi5hZnJpdnIu
Y29tMBMGA1UdIAQMMAowCAYGZ4EMAQIBMIIBBAYKKwYBBAHWeQIEAgSB9QSB8gDw
AHYAtz77JN+cTbp18jnFulj0bF38Qs96nzXEnh0JgSXttJkAAAGIxTOECAAABAMA
RzBFAiBSb7ssu+4XK1NRsXnV4eeI7mHcnJm57p9enU/2N019QgIhAJLMIyZeb/Mf
P9NKPCbpeHp5ld48TS91Jm1Z4cPDjuyFAHYA6D7Q2j71BjUy51covIlryQPTy9ER
a+zraeF3fW0GvW4AAAGIxTOEBAAABAMARzBFAiAYr5lgHDg7JfQrMA4t9Z7GybWD
DfhS7/SJyklAwWNULAIhAPMBI4FKxrN91iIKiQN3OfD0ibiQGlQgHz9s5w6YInTa
MA0GCSqGSIb3DQEBCwUAA4IBAQCe1q3OaK9kakvORWXshHMw7aegML0YG7e/M8Ma
2KBkOAl9X0+Jy0c7Hn26fN6ZudWeOHE4PngY1tTKGoUm2PKVesYt7sP8Ivo+/NTo
B1+C/q1Mdwv/vcewmw2n6/flTnvvmw6s9zXpRVJJ2sD2jAwIByMNWN8naegz2f1g
3HEPOtKVosX0zYXpFflPkGTRui0FgpiCQq0/3MaFXAu3/aSbh6Fczb1/JaAswarK
LhlGP5mNHorLbFea+B7lmIeUf9gosUrZ3cjfBVKknWrBg//DzTpf+YS1nte+Kk6S
FoLSAh7OePSmFM0okO6iyDLxmGFAja2D+CZCQbR5Y+TVi7T1
-----END CERTIFICATE-----';

$ok = openssl_verify(
    $data,
    base64_decode($signature),
    $publicKey,
    'sha256WithRSAEncryption'
);

if ($ok == 1) {
    echo "good";
} elseif ($ok == 0) {
    echo "bad";
} else {
    echo "error checking signature";
}
?>

JS

const crypto = require('crypto');

const data = "Hello World";

const signature = 'ktRxi//UUzVK8Pi5ICRSs5nCaK2g5Op+BM2mq4BK6zrb+A2392fiuFBoNj4yBWLfJxzzl1IwgVgQbjjrnbJ3i4kpYTZQ1nG82zpD7SAiF6qWq06YHR5Hrp0uvkiCKHt6pDYkXsCIph8VQqp61uplv3gifTtMRR1BGXwcxfWdrTheiFGWPnlijFaoMgLOG5CVfQAif9E7zx2ybDYtu2mMnxUWAld5bxNZXMKG87NGQ42tLaUE5OYv5yJz0kZZPZFZ5d0neGLAdm+Njf5zWlOw==';

const publicKeyPem = `-----BEGIN CERTIFICATE-----
MIIFMDCCBBigAwIBAgISA8MYezqjKnHZa+83lO64HqQoMA0GCSqGSIb3DQEBCwUA
MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD
EwJSMzAeFw0yMzA2MTYxNjE0MjdaFw0yMzA5MTQxNjE0MjZaMB4xHDAaBgNVBAMT
E3BheW1lbnRzLmFmcml2ci5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
AoIBAQDCFjhZsB7yR669TQ7mxWo9w7ajiT8Z3VZUrWSm0SKmsoxgQ1oDb1yDWIDU
fNCGQvaoRcxBfB+g9D3rhiGtX5oi8FhSFSEuNFXRN3kTVm8vRmfFdY45sjBdtF0j
8RjGwskqSzCzciXfSLoeKoLubUMcCTmUC9FLkwDqkQHedswcYG5AalvBqT7eqtBe
zip1+tVdZSVq79m5EJw98ccLF42cinkoqK76Mg2uss0mNuvpSxFN7gn/0XhaLl5U
5F2kwQr3qsijWLHqOm2cHyGOeiVScbJexvhnVMlJMEblHU/x/K6gZTCj4+O7KDgg
Gh3LHmZJ9sAtRudvM/16jGxIGoknAgMBAAGjggJSMIICTjAOBgNVHQ8BAf8EBAMC
BaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAw
HQYDVR0OBBYEFMJallKq+V5W8oqJPkmioUIvRMKGMB8GA1UdIwQYMBaAFBQusxe3
WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0
cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5j
ci5vcmcvMFsGA1UdEQRUMFKCE3BheW1lbnRzLmFmcml2ci5jb22CDnNydi5hZnJp
dnIuY29tghd3d3cucGF5bWVudHMuYWZyaXZyLmNvbYISd3d3LnNydi5hZnJpdnIu
Y29tMBMGA1UdIAQMMAowCAYGZ4EMAQIBMIIBBAYKKwYBBAHWeQIEAgSB9QSB8gDw
AHYAtz77JN+cTbp18jnFulj0bF38Qs96nzXEnh0JgSXttJkAAAGIxTOECAAABAMA
RzBFAiBSb7ssu+4XK1NRsXnV4eeI7mHcnJm57p9enU/2N019QgIhAJLMIyZeb/Mf
P9NKPCbpeHp5ld48TS91Jm1Z4cPDjuyFAHYA6D7Q2j71BjUy51covIlryQPTy9ER
a+zraeF3fW0GvW4AAAGIxTOEBAAABAMARzBFAiAYr5lgHDg7JfQrMA4t9Z7GybWD
DfhS7/SJyklAwWNULAIhAPMBI4FKxrN91iIKiQN3OfD0ibiQGlQgHz9s5w6YInTa
MA0GCSqGSIb3DQEBCwUAA4IBAQCe1q3OaK9kakvORWXshHMw7aegML0YG7e/M8Ma
2KBkOAl9X0+Jy0c7Hn26fN6ZudWeOHE4PngY1tTKGoUm2PKVesYt7sP8Ivo+/NTo
B1+C/q1Mdwv/vcewmw2n6/flTnvvmw6s9zXpRVJJ2sD2jAwIByMNWN8naegz2f1g
3HEPOtKVosX0zYXpFflPkGTRui0FgpiCQq0/3MaFXAu3/aSbh6Fczb1/JaAswarK
LhlGP5mNHorLbFea+B7lmIeUf9gosUrZ3cjfBVKknWrBg//DzTpf+YS1nte+Kk6S
FoLSAh7OePSmFM0okO6iyDLxmGFAja2D+CZCQbR5Y+TVi7T1
-----END CERTIFICATE-----`;

function verifySignature(publicKeyPem, data, signature) {
  const publicKey = crypto.createPublicKey(publicKeyPem);
  const verifier = crypto.createVerify('SHA256');
  verifier.update(data);
  const isVerified = verifier.verify(publicKey, Buffer.from(signature, 'base64'));

  return isVerified;
}

const result = verifySignature(publicKeyPem, data, signature);

if (result) {
  console.log("good");
} else {
  console.log("bad");
}