Guides
Webhooks
Receive real-time notifications when accounts and transactions change.
Webhooks let DRUO notify your server as soon as something happens, so you don't have to poll the API. DRUO sends an HTTP POST request with the affected object to the URL you register.
Create an endpoint
- 1Sign in to the DRUO portal and open Webhooks (
https://portal.druo.com/webhooks). - 2Click Create webhook endpoint.
- 3Enter your endpoint URL, a description, and the events to subscribe to.
- 4Optionally set a secret key. DRUO uses it to sign every payload.
- 5Optionally add headers that DRUO will forward with every request.
- 6Click Add endpoint. New endpoints are active by default.
To edit, enable or disable an endpoint later, open it from the Webhooks page and use the actions in the top-right corner.
Event types
| Event | When it fires |
|---|---|
Transaction.created | A transaction was created. |
Transaction.successful | A transaction completed successfully. |
Transaction.failed | A transaction failed. |
Transaction.updated | A transaction changed status or data. |
Transaction.cancelled | A transaction was canceled. |
Account.created | An account was created. |
Account.connected | An account was connected successfully. |
Account.connection-failed | An account connection attempt failed. |
Account.updated | An account changed status or data. |
Account.disconnected | An account was disconnected. |
The payload for every event of the same object type (Account, Transaction, End User) has the same structure as that object in the API reference.
Verify signatures
If you set a secret key, every request includes an X-DRUO-Webhook-Event-Signature header. Recompute it and compare before trusting the payload:
- 1Hash the raw request body with SHA-256.
- 2Compute an HMAC-SHA512 of your endpoint URL concatenated with that hash, using your secret key.
- 3Base64-encode the result and compare it with the header using a constant-time comparison.
Node.js
import crypto from "node:crypto";
export function isValidDruoSignature(rawBody, endpointUrl, secret, header) {
const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex");
const expected = crypto
.createHmac("sha512", secret)
.update(endpointUrl + bodyHash)
.digest("base64");
const a = Buffer.from(expected);
const b = Buffer.from(header ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Python
import base64, hashlib, hmac
def is_valid_druo_signature(raw_body: bytes, endpoint_url: str, secret: str, header: str) -> bool:
body_hash = hashlib.sha256(raw_body).hexdigest()
digest = hmac.new(secret.encode(), (endpoint_url + body_hash).encode(), hashlib.sha512).digest()
expected = base64.b64encode(digest).decode()
return hmac.compare_digest(expected, header or "")Always verify against the raw body bytes, before any JSON parsing. Respond with a 2xx status quickly and do heavy work asynchronously.

