Webhooks

Webhook events notify your application when specific actions occur in your 1Money account. Your endpoint must respond with a 2xx status code within 10 seconds.

Webhook Events

Detailed onboarding-specific payload guidance is documented separately for Business Onboarding Webhooks and Individual Onboarding Webhooks.

HTTP Headers

All webhook requests include the following headers:

Signature Verification

To verify webhook authenticity, compute the HMAC-SHA256 signature and compare it with X-Webhook-Signature.

Algorithm

signed_payload = "{timestamp}.{request_body}"
expected_signature = HMAC-SHA256(signed_payload, webhook_secret)

Verification Steps

1. Extract X-Webhook-Signature and X-Webhook-Timestamp from headers
2. Concatenate: {timestamp}.{raw_request_body}
3. Compute HMAC-SHA256 using your webhook secret
4. Compare signatures using constant-time comparison
5. Reject if timestamp is older than 5 minutes (replay attack prevention)

Code Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  // Check timestamp (5 minute tolerance)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Code Example (Python)

import hmac
import hashlib
import time

def verify_webhook_signature(payload: str, signature: str, timestamp: int, secret: str) -> bool:
    # Check timestamp (5 minute tolerance)
    now = int(time.time())
    if abs(now - timestamp) > 300:
        return False

    # Compute expected signature
    signed_payload = f"{timestamp}.{payload}"
    expected_signature = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(signature, expected_signature)

Payload Structure

All webhook payloads follow this structure:

{
  "event_name": "event.type",
  "resource": {
    "type": "resource_type",
    "id": "resource_id",
    "idempotency_key": "client_passed_idempotency_key"
  },
  "data": {
    // Event-specific data
  }
}

Retry Policy

If your endpoint does not respond with a 2xx status code, we will retry the webhook delivery:

After 5 failed attempts (approximately 15.5 hours total), the webhook is marked as permanently failed

Best Practices

1. Respond quickly - Return 200 OK immediately, process asynchronously
2. Verify signatures - Always validate X-Webhook-Signature before processing
3. Handle duplicates - Use X-Webhook-Event-Id for idempotency
4. Use HTTPS - Webhook endpoints must use HTTPS
5. Log deliveries - Track X-Webhook-Delivery-Id for debugging