Webhook validation

Signature headers

Each webhook request includes:

• x-timestamp - Unix timestamp in seconds
• x-signature - HMAC SHA-256 signature calculated from the timestamp and raw request body

Create a signing secret

Create the webhook signing secret in Developer settings in the partner portal:

1. Open Webhook settings.
2. Add the webhook endpoint URL.
3. Select the event categories for the endpoint. All categories are enabled by default.
4. Select Generate webhook secret or Regenerate webhook secret.
5. Copy the secret and store it in a secrets manager or equivalent encrypted secrets store. The secret is shown once.

Signature input

Admiin calculates the signature using HMAC SHA-256:

signature = HMAC-SHA256(secret, timestamp + "." + rawBody)

Validation procedure

1. Read the headers

Read the timestamp and signature from the request headers:

const timestamp = request.headers['x-timestamp'];
const providedSignature = request.headers['x-signature'];

2. Read the raw request body

Use the raw, unparsed request body. Do not parse the body as JSON before validating the signature.

// Express example using the raw body parser
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  // ... validate signature
});

3. Calculate the expected signature

Calculate the signature using the timestamp and raw request body:

const crypto = require('crypto');

const expectedSignature = crypto.createHmac('sha256', webhookSecret).update(`${timestamp}.${rawBody}`).digest('hex');

4. Compare the signatures

Use constant-time comparison to prevent timing attacks:

const isValid = crypto.timingSafeEqual(Buffer.from(expectedSignature, 'hex'), Buffer.from(providedSignature, 'hex'));

5. Validate and respond

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

// Parse and process webhook
const payload = JSON.parse(rawBody);
// ... handle webhook event

res.status(200).json({ received: true });

Node.js and Express example

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.headers['x-timestamp'];
  const signature = req.headers['x-signature'];
  const rawBody = req.body.toString('utf8');

  // Validate the timestamp to prevent replay attacks
  const currentTime = Math.floor(Date.now() / 1000);
  const timeDiff = Math.abs(currentTime - parseInt(timestamp));

  if (timeDiff > 300) {
    // 5 minutes
    return res.status(400).json({ error: 'Timestamp too old' });
  }

  // Validate signature
  const expectedSignature = crypto.createHmac('sha256', WEBHOOK_SECRET).update(`${timestamp}.${rawBody}`).digest('hex');

  const isValid = crypto.timingSafeEqual(Buffer.from(expectedSignature, 'hex'), Buffer.from(signature, 'hex'));

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook
  const event = JSON.parse(rawBody);
  console.log('Received webhook:', event.type);

  // Handle different event types
  switch (event.type) {
    case 'payment.succeeded':
      // Handle successful payment
      handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      // Handle failed payment
      handlePaymentFailed(event.data);
      break;
    default:
      console.log('Unknown event type:', event.type);
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Other language examples

Python (Flask)

from flask import Flask, request, jsonify
import hmac
import hashlib
import time
import os

app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get('WEBHOOK_SECRET')

@app.route('/webhook', methods=['POST'])
def webhook():
    timestamp = request.headers.get('x-timestamp')
    provided_signature = request.headers.get('x-signature')
    raw_body = request.get_data(as_text=True)

    # Validate timestamp
    current_time = int(time.time())
    time_diff = abs(current_time - int(timestamp))

    if time_diff > 300:  # 5 minutes
        return jsonify({'error': 'Timestamp too old'}), 400

    # Compute expected signature
    message = f"{timestamp}.{raw_body}".encode('utf-8')
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        message,
        hashlib.sha256
    ).hexdigest()

    # Validate signature (constant-time comparison)
    if not hmac.compare_digest(expected_signature, provided_signature):
        return jsonify({'error': 'Invalid signature'}), 401

    # Process webhook
    event = request.get_json()
    print(f"Received webhook: {event['type']}")

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

PHP

<?php

$webhookSecret = getenv('WEBHOOK_SECRET');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$providedSignature = $_SERVER['HTTP_X_SIGNATURE'];
$rawBody = file_get_contents('php://input');

// Validate timestamp
$currentTime = time();
$timeDiff = abs($currentTime - intval($timestamp));

if ($timeDiff > 300) { // 5 minutes
    http_response_code(400);
    echo json_encode(['error' => 'Timestamp too old']);
    exit;
}

// Compute expected signature
$expectedSignature = hash_hmac('sha256', "$timestamp.$rawBody", $webhookSecret);

// Validate signature (constant-time comparison)
if (!hash_equals($expectedSignature, $providedSignature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Process webhook
$event = json_decode($rawBody, true);
error_log("Received webhook: " . $event['type']);

// Handle event
switch ($event['type']) {
    case 'payment.succeeded':
        // Handle successful payment
        break;
    case 'payment.failed':
        // Handle failed payment
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);
?>

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "log"
    "math"
    "net/http"
    "os"
    "strconv"
    "time"
)

var webhookSecret = os.Getenv("WEBHOOK_SECRET")

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    timestamp := r.Header.Get("x-timestamp")
    providedSignature := r.Header.Get("x-signature")

    rawBody, err := ioutil.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Failed to read body", http.StatusBadRequest)
        return
    }

    // Validate timestamp
    ts, _ := strconv.ParseInt(timestamp, 10, 64)
    currentTime := time.Now().Unix()
    timeDiff := math.Abs(float64(currentTime - ts))

    if timeDiff > 300 { // 5 minutes
        http.Error(w, "Timestamp too old", http.StatusBadRequest)
        return
    }

    // Compute expected signature
    message := fmt.Sprintf("%s.%s", timestamp, string(rawBody))
    h := hmac.New(sha256.New, []byte(webhookSecret))
    h.Write([]byte(message))
    expectedSignature := hex.EncodeToString(h.Sum(nil))

    // Validate signature (constant-time comparison)
    if subtle.ConstantTimeCompare([]byte(expectedSignature), []byte(providedSignature)) != 1 {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // Process webhook
    var event map[string]interface{}
    json.Unmarshal(rawBody, &event)
    log.Printf("Received webhook: %s", event["type"])

    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]bool{"received": true})
}

func main() {
    http.HandleFunc("/webhook", webhookHandler)
    log.Println("Webhook server running on port 3000")
    log.Fatal(http.ListenAndServe(":3000", nil))
}

Security requirements

• Validate the signature on every webhook request.
• Reject timestamps older than five minutes to prevent replay attacks.
• Calculate the signature from the raw request body before JSON parsing.
• Compare signatures using a constant-time function.
• Store the webhook secret in a secrets manager or equivalent encrypted secrets store.
• Accept webhook requests over HTTPS only.
• Return a 2xx response within five seconds after validation.
• Process long-running work asynchronously.
• Handle repeated deliveries idempotently.
• Record webhook attempts without logging secrets or sensitive request data.
• Do not trim or modify the raw request body before validation.
• Do not rely on IP filtering as the only validation control.

Testing

Local testing

Use an HTTPS tunnel such as ngrok to expose a local endpoint:

ngrok http 3000
# Use the https URL as your webhook endpoint

Then configure the endpoint in Developer settings:

1. Open Webhook settings.
2. Add the HTTPS tunnel URL, for example https://your-ngrok-url.ngrok.io/webhook.
3. Save the endpoint.

Retry a notification

Retry a webhook notification using:

POST /v1/webhook-notifications/{id}/retry

This operation retries delivery to the configured endpoint.

Webhook payload format

Every event body is flat. type is the discriminator and occurredAt is an ISO-8601 timestamp; the remaining fields depend on the event. There is no data wrapper.

{
  "type": "payment.succeeded",
  "id": "pay_123",
  "amount": 10000,
  "status": "PAYOUT_SENT",
  "commissionAmount": 250,
  "metadata": {
    "customField": "value"
  },
  "occurredAt": "2026-01-15T10:30:00.000Z"
}

status is supplementary. It is the internal status value, kept for partners who key off it today, but type is the canonical discriminator. Branch on type and ignore any event type you do not handle, so a new one cannot break your receiver.

Event types

Payment events

Verification and business lookup events

There is no verification.individual.link_ready or link_sent event. The POST /v1/verifications/{verificationId}/links response returns each verificationUrl synchronously. The next webhook event is verification.individual.in_progress when the customer opens the link.

Payload privacy contract (APP 3.2 data minimisation). Verification webhook payloads do NOT carry partner end-user PII (firstName / lastName / email / phone). Per-individual events expose individualId and (when supplied at create time) the partner-supplied opaque externalId. business-lookup.completed exposes entity.name and per-UBO idvEntityId only. UBO names are NOT included.

Customer billing events

Sent when you bill a contact's saved card. Every event carries contactId and channelPartnerId. See Customer billing.

Trust deed analysis events

Sent when a trust deed finishes analysis. See Trust deed analysis.

Deed payloads are delivery-only. These events carry extracted party detail, so the stored notification record holds no payload: GET /v1/webhook-notifications returns payload: null for the deed-analysis category and those records carry a short retention. Capture what you need from the delivery itself.

Monitoring events

Sent by continuous monitoring. Every event carries contactId and product. See Continuous monitoring.

Monitoring payloads are a deliberate minimum. No name, no screening-service entity id, no article snippets or URLs and no raw match records are pushed. Read the detail from the alert and evidence routes once you hold a monitoringAlertId.

Continuous monitoring runs only in the screening service's production environment, so no monitoring.* event occurs naturally on dev or demo. Use the signed test webhook with type=monitoring and a variant to exercise a receiver there.

Monitoring event payload examples

Alert created:

{
  "type": "monitoring.alert.created",
  "monitoringAlertId": "mon_alert_demo_00000000000000000000",
  "contactId": "contact_demo_monitoring_00000000",
  "product": "INDIVIDUAL_AML",
  "categories": ["SANCTION", "PEP", "ADVERSE_MEDIA"],
  "status": "OPEN",
  "occurredAt": "2026-05-17T10:00:00.000Z"
}

Coverage mismatch:

{
  "type": "monitoring.subscription.coverage_mismatch",
  "contactId": "contact_demo_monitoring_00000000",
  "product": "INDIVIDUAL_AML",
  "requestedCoverage": "PEP_SANCTIONS_MEDIA",
  "observedCoverage": "PEP_SANCTIONS",
  "occurredAt": "2026-05-17T10:00:00.000Z"
}

Verification event payload examples

KYB lookup completed:

{
  "type": "business-lookup.completed",
  "lookupRequestId": "kyb_01J9AB...",
  "channelPartnerId": "partner_01J9AB...",
  "entity": {
    "name": "Acme Pty Ltd",
    "type": "COMPANY"
  },
  "individuals": [{ "idvEntityId": "fe_alice_..." }, { "idvEntityId": "fe_bob_..." }],
  "occurredAt": "2026-05-18T03:21:00Z"
}

UBO names are omitted from this payload. Query ASIC or ABR using the ABN or ACN supplied with the lookup if names are required. The individuals[] array is always present and contains one idvEntityId for each discovered UBO. Pass the idvEntityId and an optional partner externalId to POST /v1/verifications to enrol the UBO for identity verification.

Individual passed:

{
  "type": "verification.individual.passed",
  "verificationRequestId": "vr_01J9AB...",
  "individualId": "vi_01J9AB...",
  "status": "PASSED",
  "manualOverride": false,
  "attemptCount": 1,
  "completedAt": "2026-05-18T03:25:42Z",
  "occurredAt": "2026-05-18T03:25:42Z"
}

Individual manual review:

{
  "type": "verification.individual.manual_review",
  "verificationRequestId": "vr_01J9AB...",
  "individualId": "vi_01J9AB...",
  "status": "MANUAL_REVIEW",
  "occurredAt": "2026-05-18T03:25:42Z"
}

Individual locked out:

{
  "type": "verification.individual.locked_out",
  "verificationRequestId": "vr_01J9AB...",
  "individualId": "vi_01J9AB...",
  "status": "LOCKED_OUT",
  "attemptCount": 5,
  "maxAttempts": 5,
  "occurredAt": "2026-05-18T03:30:11Z"
}

Process verification events

Verification events use the same HMAC validation process as payment events. Handle each value of event.type:

switch (event.type) {
  case 'payment.succeeded':
    handlePaymentSucceeded(event.data);
    break;
  case 'payment.failed':
    handlePaymentFailed(event.data);
    break;
  case 'business-lookup.completed':
    handleKybCompleted(event); // payload is on the event object directly
    break;
  case 'verification.individual.passed':
    handleIndividualPassed(event);
    break;
  case 'verification.individual.failed':
    handleIndividualFailed(event);
    break;
  case 'verification.individual.in_progress':
  case 'verification.individual.manual_review':
  case 'verification.individual.locked_out':
  case 'verification.individual.added':
  case 'verification.request.created':
  case 'verification.request.completed':
    handleVerificationStateChange(event);
    break;
  default:
    console.log('Unknown event type:', event.type);
}

Verification events carry their fields at the top level (not nested under data). De-duplicate by (type, verificationRequestId, individualId, occurredAt) to handle retry delivery.

Troubleshooting

Signature mismatch

• Use the raw request body, not parsed JSON.
• Confirm that the signing secret matches the endpoint configuration.
• Do not trim whitespace from the request body.
• Read the timestamp as Unix seconds, not milliseconds.
• Check whether middleware modifies the request body.

Webhooks are not received

• Confirm that the endpoint is publicly accessible over HTTPS.
• Return a 2xx response within five seconds.
• Review webhook notification records through the API.
• Check firewall and network rules.
• Confirm that the TLS certificate is valid.

Slow webhook processing

• Return a 2xx response immediately after validation.
• Place the payload on a queue for asynchronous processing.
• Avoid synchronous database and external API calls in the request handler.

Repeated webhook deliveries

• Use the webhook event ID as an idempotency key.
• Store processed event IDs to detect repeated deliveries.
• Use an atomic database write when recording processed events.

Delivery retry schedule

If the endpoint does not respond or returns a non-2xx status:

• First retry after 30 seconds
• Exponential backoff for subsequent retries
• Maximum of 10 attempts over 24 hours
• Retry count available in webhookAttempts on the notification

Notification records

Retrieve notifications

List recent webhook notifications:

GET /v1/webhook-notifications

Get details of a specific notification:

GET /v1/channel-payments/{paymentId}/webhook-notifications/{notificationId}

Response codes

The endpoint response determines retry behaviour:

• 200-299 - Delivery accepted
• 400-499 - Client error; delivery is retried
• 500-599 - Server error; delivery is retried with backoff

Support

Provide the following information when reporting a webhook issue:

• Webhook notification ID
• Timestamp of the failed delivery
• Response status and error from the endpoint
• Your signature validation implementation
• Request/response logs (excluding secrets)

Contact Admiin integration support.