Webhooks

When a TREVEX admin approves a KYB request, a POST request is sent to the webhook_url configured on your Project.

Delivery

Payload

1
{
2
  "event": "claim_approved",
3
  "request_id": "REQ-ABC123XYZ789",
4
  "trevex_company_id": "TRXAE0000042",
5
  "company": {
6
    "name": "Acme Corporation LLC",
7
    "country_code": "AE",
8
    "trade_license_url": "https://...",
9
    "industry": {
10
      "sector": "Technology",
11
      "group": "Software",
12
      "industry": "SaaS",
13
      "sub_industries": ["Cloud Computing", "Artificial Intelligence"]
14
    },
15
    "address": {
16
      "line_1": "123 Sheikh Zayed Road",
17
      "city": "Dubai",
18
      "country": "UAE"
19
    },
20
    "authorized_signatory": {
21
      "name": "John Doe",
22
      "designation": "CEO",
23
      "email": "john@acmecorp.com",
24
      "mobile": "+971501234567",
25
      "nationality": "AE"
26
    }
27
  },
28
  "contact_email": "john.doe@example.com"
29
}

Verifying signatures

Every webhook request is signed. You must verify the signature before trusting the payload - without this, an attacker who discovers your webhook URL can forge approval events.

How the signature is built

On every delivery, TREVEX computes:

signature = HMAC_SHA256(
  secret = your_webhook_signing_secret,
  message = "{timestamp}.{raw_request_body}"
)

and sends it hex-encoded in the X-Trevex-Signature header alongside the X-Trevex-Timestamp header (Unix epoch seconds).

Headers

Verification steps

Example implementations

1
import hmac
2
import hashlib
3
import time
4
from flask import Flask, request, abort
5
6
app = Flask(__name__)
7
WEBHOOK_SECRET = b"your_webhook_signing_secret"
8
TOLERANCE_SECONDS = 300
9
10
def verify_trevex_webhook(raw_body: bytes, timestamp: str, signature: str) -> bool:
11
    # 1. Timestamp window
12
    try:
13
        ts = int(timestamp)
14
    except (TypeError, ValueError):
15
        return False
16
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
17
        return False
18
19
    # 2. Recompute
20
    message = f"{timestamp}.".encode() + raw_body
21
    expected = hmac.new(WEBHOOK_SECRET, message, hashlib.sha256).hexdigest()
22
23
    # 3. Constant-time compare
24
    return hmac.compare_digest(expected, signature)
25
26
@app.post("/webhooks/trevex")
27
def trevex_webhook():
28
    raw = request.get_data()  # raw bytes, not request.json
29
    ts = request.headers.get("X-Trevex-Timestamp", "")
30
    sig = request.headers.get("X-Trevex-Signature", "")
31
32
    if not verify_trevex_webhook(raw, ts, sig):
33
        abort(401)
34
35
    event = request.get_json()
36
    # handle event["request_id"], event["trevex_company_id"], ...
37
    return "", 200

Secret rotation

If you need to rotate your webhook signing secret, contact your TREVEX account manager. During the rotation window, TREVEX can sign with both the old and new secrets so you can switch without dropping events. Accept either signature until you’ve fully deployed the new secret, then ask TREVEX to retire the old one.

Matching webhooks to your records

Use request_id to match an incoming webhook to the KYB request you submitted. It’s the same value returned from create_claim.

trevex_company_id is the canonical TREVEX ID for the company. Store it if you plan to call update_claim later.

Handling retries

Your endpoint should be idempotent - the same request_id may arrive more than once if the first attempt fails or times out. A common pattern:

1. Look up the request_id in your database.
2. If already processed, return 200 without doing any work.
3. Otherwise, process and store.