About our webhooks

The webhook URL is defined by Processor and, for now, this configuration has to be requested to our team.

Our platform considers a webhook susccessfull if it receives a 2xx status code from your platform on the specified endpoint.

Webhook Retry Policy

When a webhook call fails (i.e., a non-2xx response is received), our system will retry sending the webhook once per minute for up to 10 minutes, totaling 10 attempts if no successful (2xx) response is received. This updated strategy promotes greater reliability for webhook delivery without putting excessive pressure on destination systems.

Signature

The webhook request includes a x-paag-webhook-signature header that contains a Base64 encoded HMAC signature of the payload. The signature is generated using the SHA256 algorithm and the secret key provided by your platform. You can use this signature to verify the authenticity of the webhook request. This is how the signature is generated:

This is an example of how you can verify the signature in a Node.js application:

var crypto = require('crypto');

// The webhook body
data = hmac.update('{"event":"transfer","transaction": .... }]}}');

var hmac = crypto.createHmac('sha256', 'SECRET_SHARED_WITH_YOU');

hmacSignature = data.digest('hex');

generatedSignature = Buffer.from(hmacSignature).toString('base64')

var expectedSignature = 'OGJkZGEzNTg0YWNiZmUwYzgzNjgyZjkzY2QzZDM5ZWJiNTdiNDFkNDMxMzc4YmI0ZjE5ZTZmM2IzOTEwYTBiZg=='

console.log("Expected Signature: " + expectedSignature);
console.log("Generated Signature: " + generatedSignature);
console.log(`Equal: ${generatedSignature == expectedSignature}`);

This is an example of how you can verify the signature in a Go application:

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "fmt"
)

func main() {
    // The webhook body
    data := []byte(`{"event":"transfer","transaction":{....}]}}`)

    secret := []byte("SECRET_SHARED_WITH_YOU")

    // create a new HMAC by defining the hash type and the key
    algo := hmac.New(sha256.New, secret)

    // compute the HMAC
    algo.Write(data)
    dataHmac := algo.Sum(nil)

    hmacHex := hex.EncodeToString(dataHmac)
    //secretHex := hex.EncodeToString(secret)

    toBase64 := base64.StdEncoding.EncodeToString([]byte(hmacHex))

    expected := "OGJkZGEzNTg0YWNiZmUwYzgzNjgyZjkzY2QzZDM5ZWJiNTdiNDFkNDMxMzc4YmI0ZjE5ZTZmM2IzOTEwYTBiZg=="
    fmt.Printf("HMAC_SHA256: %s \n", toBase64)
    fmt.Printf("Comparing: %t", toBase64 == expected)
}