Event Streaming

Async Telemetry

Streaming Engine Active

Webhooks & Event Streams

Authepy executes operations asynchronously via the Edge. To react to downstream provider events—such as hard bounces, spam complaints, or delayed deliveries—you must configure Webhooks.

Asynchronous Event Topologies

When an event triggers inside Authepy's internal routing clusters, a JSON payload is fired to your configured HTTPS endpoint. These events allow you to purge invalid emails from your CRM or trigger in-app alerts.

Core Event Types

verification.success
Fires the exact millisecond a token is verified. Ideal for decentralized applications that rely entirely on off-chain webhook syncing to provision on-chain resources.
delivery.bounced
Triggered if the downstream ISP rejects the payload. The payload `data` object will contain the specific SMTP diagnostic code (e.g., mailbox_full, domain_not_found).
delivery.spam
Fires if the end-user marks the verification email as junk. You should programmatically blacklist this user in your database to preserve your sender reputation.

Standard JSON Payload Webhook Object

{
  "event_id": "evt_9x8c7v6b5a4",
  "type": "delivery.bounced",
  "created_at": 1694285400,
  "data": {
    "requestId": "req_8f7d6c5b4a3",
    "email": "user@domain.com",
    "bounce_reason": "mailbox_full",
    "provider_latency_ms": 142
  }
}

Cryptographic Signature Verification

Because your webhook endpoint must remain publicly accessible on the internet, malicious actors can send forged requests to it. To guarantee a payload originated legitimately from Authepy's infrastructure, we append an Authepy-Signature HTTP header to every transmission.

Security Requirement

You must evaluate the signature using an HMAC with the SHA-256 hash function. Do not parse the incoming JSON before generating the hash; you must hash the raw binary buffer of the request body, or the signature will fail.

Express.js Middleware Verification Node.js Crypto

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

// Use express.raw() to preserve the exact payload bytes for cryptographic hashing
app.post('/webhooks/authepy', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['authepy-signature'];
  const payload = req.body; // Raw buffer
  const secret = process.env.AUTHEPY_WEBHOOK_SECRET;

  // 1. Compute the expected HMAC SHA-256 hash
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // 2. Perform a timing-safe comparison to prevent timing attacks
  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    const event = JSON.parse(payload.toString());
    
    // 3. Process the asynchronous event asynchronously
    handleAuthepyEvent(event);
    
    // 4. Return a 200 OK instantly to acknowledge receipt
    return res.status(200).send('Webhook verified');
  }

  // Reject unauthorized payloads
  return res.status(401).send('Invalid cryptographic signature');
});

Delivery Retries & Timeouts

Authepy expects your webhook endpoint to return a 2xx HTTP status code within 5,000 milliseconds (5 seconds). If your server times out, drops the connection, or returns a 4xx or 5xx response, the Edge Router places the payload into an exponential backoff queue.

Exponential Backoff Schedule

Initial Failure → Retry at +5 Mins → Retry at +30 Mins → Retry at +2 Hours

After the final failed attempt, the event is permanently discarded from the streaming queue. Ensure you execute long-running database tasks asynchronously after returning the 200 OK to avoid timeouts.

Previous ← Integration Guide Next Rate Limits & Active Bans →