Skip to main content
Webhooks notify your application in real time when transaction events occur. Configure a webhook URL to receive updates for deposits, conversions, transfers, onramp requests, and offramp requests.

​
Setup

Configure your webhook URL through the dashboard or programmatically via the Update Webhook URL endpoint. Your endpoint must be a publicly accessible POST URL that returns a 200 status code immediately. Process events asynchronously after acknowledging receipt.

​
Receiving events

Every webhook payload includes three fields:
FieldTypeDescription
eventstringThe event type (e.g., Deposit, Convert, Transfer)
dataobjectEvent-specific payload
signaturestringRSA signature for verification

​
Supported events

EventDescription
DepositA fiat or crypto deposit was received
ConvertA currency conversion completed
TransferA transfer (payout/withdrawal) status changed
OnrampAn onramp (fiat-to-crypto) request status changed
WithdrawalA withdrawal was processed
OfframpAn offramp (crypto-to-fiat) request status changed
verification.successA user successfully completed KYC verification
verification.failedA user failed KYC verification (includes reason)

​
Sample events

{
  "event": "Deposit",
  "data": {
    "amount": 5001,
    "toUser": "chng",
    "currency": "NGN",
    "toAccount": "chng",
    "status": "completed",
    "sessionId": "3c58db9",
    "transactionMemo": "Mock Deposit"
  },
  "signature": "m9STu6pcsviYMfgu5JBjuR"
}

​
Verifying signatures

Every webhook includes an RSA signature. Always verify the signature before processing an event to confirm it came from Partna. The signature is generated by signing the JSON-encoded data field with Partna’s RSA private key using SHA-256 with PSS padding. Verify it against the corresponding public key for your environment. 
import crypto from "crypto";

const SAMPLE_WEBHOOK_REQUEST = `{"event":"Convert","data":{"transactionReference":"a1632e4ea53f2802846cf7797d29bfba","fromUser":"eltnegbiz2","toAccount":"eltnegbiz2","timestamp":1775132847,"fromAmount":1,"toAmount":1000.5,"fromCurrency":"USD","toCurrency":"NGN"},"signature":"ISPOtoKOJRSuT0rKoz0P7JSPSna6UztGOrkKJKWSn62SqUobtaCYURVbhE6A8eIt82qJ9+32XlK1GJZkA5A64MYuDBLF9MdlHvfuNDkPRTof4RV+8UdlSifmBqAU2oYtvA6z4aFHUdiRcfpPNSdkRmLARwIbBxv9Zg6GHFV5HKqybMNt0QaCQskUWVcWOnCEf9PpKV1cKhJWWchYNpiCJgcV8N/vUgOFFVymhkXzbfZADuLukEwScJ751Ll97wWpLwZ1s+1DoBNQ5cY32ft80c3fwnO1NpAW/n22Bpf82rdLP1JctaJUV/3yuorMh+qNaKaXocAMpn6Vkxu8NdyNdQ=="}`;

const PUBLIC_KEY = `-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAv2ipgHLFFHgGHr9VpsPN8V1HIbCrlmTZRU/CYSDaoVX+xerJOMGX
qmwgQMQH5T81VaMw4rtIA8tT4DkJgjb+7G0x4CGK1OPdlvhEGP2mOFy02onkEnMv
uN3glVc4YKLvWDTG0KT7q9mARBIkO2Nrwy6IVHAl9pMXMJTRS22c0cIbuRmkYsGZ
trylUv50knbRSgy5EA6523+j3PPJB4TgsigGSJxJGuksaxnDQGRE558xnyw/0gJm
mAIdbxboQTGMqod/My/kAssRkUNu1QtqrsdhZmGYHS+pIPJSaxqHEy8eiTahoqqq
8KgNUfQfwduG+Kc4f/t5JHetSt1dgulmswIDAQAB
-----END RSA PUBLIC KEY-----`;

function verifySignature(data: string, signature: string) {
  return crypto.verify(
    "sha256",
    Buffer.from(JSON.stringify(data), "utf8"),
    {
      key: PUBLIC_KEY,
      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
    },
    Buffer.from(signature, "base64"),
  );
}

function run() {
  const { event, data, signature } = JSON.parse(SAMPLE_WEBHOOK_REQUEST);

  const isValid = verifySignature(data, signature);

  if (isValid) {
    console.log("Signature is valid. Processing event:", event);
    // Process the event data as needed
  } else {
    console.error("Invalid signature. Possible tampering detected.");
  }
}
run();

​
Public keys

Use the correct public key for your environment.

​
Staging

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAv2ipgHLFFHgGHr9VpsPN8V1HIbCrlmTZRU/CYSDaoVX+xerJOMGX
qmwgQMQH5T81VaMw4rtIA8tT4DkJgjb+7G0x4CGK1OPdlvhEGP2mOFy02onkEnMv
uN3glVc4YKLvWDTG0KT7q9mARBIkO2Nrwy6IVHAl9pMXMJTRS22c0cIbuRmkYsGZ
trylUv50knbRSgy5EA6523+j3PPJB4TgsigGSJxJGuksaxnDQGRE558xnyw/0gJm
mAIdbxboQTGMqod/My/kAssRkUNu1QtqrsdhZmGYHS+pIPJSaxqHEy8eiTahoqqq
8KgNUfQfwduG+Kc4f/t5JHetSt1dgulmswIDAQAB
-----END RSA PUBLIC KEY-----

​
Production

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAoGmOqVUxIGq92P8J5KqwJbwucsNeUwfS76saj0UPgT1IsK/mvceR
Ges7dsgE4EVx7Wsd5PPNeAfaNt8d0plBLhHRW64WFyv6jYcYp8eVdHUxWLA6p5gZ
9rGrZiwqKqunppTPlV04gdDC32rAbpAR3IMYmMJLuPy63Oumszl4qk69A1o60Son
r0KYBaRK7aQsFT9IFexicDUhrF1SohaNH/msTdvJb0SwSGiV92EhmmC2R8CL83/B
S8QC5c9PWtZ4a26CRLHe0IfaGGz8ClhlO8IFxz0cNrpoRa4JRsffezQ+RMQqCxhc
igC7wHfqZr5BtziQOYJjUknVzsd81HEYlwIDAQAB
-----END RSA PUBLIC KEY-----

​
Best practices

Always verify signatures. Never process a webhook event without verifying the signature first. This prevents spoofed events from affecting your system. Return 200 immediately. Acknowledge receipt before processing. If your endpoint takes too long to respond, the delivery may be retried. Handle duplicates. Use the sessionId or rampReference in the event data as an idempotency key. The same event may be delivered more than once. Log raw payloads. Store the raw webhook body for debugging. If something goes wrong, the raw payload is essential for troubleshooting.