Webhooks

How Webhooks Work

When something happens in your tenant — a user registers, a login fails, a session is revoked — Vyntech Account fires an event. If you have a webhook registered for that event type, here's what happens:

1. 1An event occurs in your tenant (e.g., a user registers).
2. 2The payload is constructed with full event details and signed using HMAC-SHA256 with your webhook secret.
3. 3A POST request is sent to your registered endpoint with the payload as JSON body and the signature in the X-Webhook-Signature header.
4. 4Your endpoint must respond with a 2xx status within 10 seconds.
5. 5If delivery fails, the system retries with exponential backoff (up to 3 attempts).

Event Types

Subscribe to specific events or use * to receive all events. Events follow a resource.action naming convention.

Payload Format

Every webhook delivery sends a JSON payload with a consistent structure. TheX-Webhook-Signature header contains the HMAC-SHA256 signature of the raw request body.

Headers

Example Payload

{
  "id": "evt_01H9ABCD4F2B7NQ9RPWT3M6J",
  "event": "user.registered",
  "tenant_id": "tnt_01H7ABCD5E3C8MR0QPXS4N7K",
  "timestamp": "2024-11-15T09:32:17Z",
  "data": {
    "user_id": "usr_01H8KXYZ4F2B7NQ9RPWT3M6J",
    "email": "jane@acme-corp.com",
    "display_name": "Jane Smith",
    "status": "active",
    "email_verified": false,
    "mfa_enabled": false
  }
}

Configuring your Webhook

Webhook configuration is managed through the Tenant Settings API. You can configure a single webhook URL per tenant and specify which events it should receive. A shared secret must also be provided for signature verification.

{
  "notifications": {
    "webhook_url": "https://your-app.com/webhooks/vyntech",
    "webhook_events": ["user.registered", "auth.login", "auth.login.failed"],
    "webhook_secret": "whsec_your_shared_secret_here"
  }
}

Signature Verification

Every webhook delivery includes an X-Webhook-Signatureheader containing a HMAC-SHA256 signature of the raw request body, computed with your shared secret. Always verify this signature before processing the event to ensure the request came from Vyntech Account and wasn't tampered with.

How It Works

1. 1Read the raw request body (do not parse JSON first — the signature is over the raw bytes).
2. 2Compute HMAC-SHA256 of the raw body using your webhook secret as the key.
3. 3Compare your computed signature with the value in X-Webhook-Signature (after stripping the sha256= prefix).
4. 4Use a constant-time comparison to prevent timing attacks.

Verification Examples

Retry Policy

If your endpoint doesn't respond with a 2xx status within 10 seconds, or if the connection fails, Vyntech Account will retry delivery with exponential backoff.

Failure Escalation

• •After 3 consecutive failures for a single event, the delivery is marked as failed and won't be retried.
• •If a webhook accumulates failures over time, it's marked as failing — events continue to be sent but you'll see warnings in the admin dashboard.
• •After 24 hours of continuous failures, the webhook is automatically disabled. You'll receive an email notification and must re-enable it manually.

Best Practices

What's Next