DRUO
Get started
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

  1. 1Sign in to the DRUO portal and open Webhooks (https://portal.druo.com/webhooks).
  2. 2Click Create webhook endpoint.
  3. 3Enter your endpoint URL, a description, and the events to subscribe to.
  4. 4Optionally set a secret key. DRUO uses it to sign every payload.
  5. 5Optionally add headers that DRUO will forward with every request.
  6. 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

EventWhen it fires
Transaction.createdA transaction was created.
Transaction.successfulA transaction completed successfully.
Transaction.failedA transaction failed.
Transaction.updatedA transaction changed status or data.
Transaction.cancelledA transaction was canceled.
Account.createdAn account was created.
Account.connectedAn account was connected successfully.
Account.connection-failedAn account connection attempt failed.
Account.updatedAn account changed status or data.
Account.disconnectedAn 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:

  1. 1Hash the raw request body with SHA-256.
  2. 2Compute an HMAC-SHA512 of your endpoint URL concatenated with that hash, using your secret key.
  3. 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.