Webhooks API

sequenceDiagram    autonumber    actor Sender as Inbound Email Sender    participant Engine as AliasFleet Ingestion Engine    participant Rules as Rules Engine    participant Egress as Anti-SSRF Dispatcher    participant Customer as Your Webhook Server (HTTPS)    Sender->>Engine: Inbound Message Envelope    Engine->>Rules: Evaluate Inbound Rules    Rules->>Rules: Action: send_to_webhook (Endpoint ID)    Rules->>Egress: Assemble Payload & Sign HMAC-SHA256    Egress->>Egress: Validate Egress IP (Reject RFC 1918 / Metadata)    Egress->>Customer: POST /webhook (X-AliasFleet-Signature)    Customer-->>Egress: 200 OK    Egress->>Engine: Record Delivery Log (Latency & Status)

Signed Payload     = timestamp + "." + rawRequestBodyExpected Signature = HMAC-SHA256(secret_key, Signed Payload)

// app/api/webhook/route.tsimport { NextResponse } from 'next/server';import crypto from 'node:crypto';export async function POST(req: Request) {  const signatureHeader = req.headers.get('x-aliasfleet-signature');  const secretKey = process.env.ALIASFLEET_WEBHOOK_SECRET!;  if (!signatureHeader || !secretKey) {    return NextResponse.json({ error: 'Missing signature credentials' }, { status: 401 });  }  // Read raw text before JSON parsing  const rawBody = await req.text();  const parts = Object.fromEntries(    signatureHeader.split(',').map((kv) => kv.trim().split('='))  );  const timestamp = parseInt(parts.t, 10);  const receivedSig = parts.v1;  if (!timestamp || !receivedSig) {    return NextResponse.json({ error: 'Malformed signature header' }, { status: 400 });  }  // Tolerance check (5 minutes)  const now = Math.floor(Date.now() / 1000);  if (Math.abs(now - timestamp) > 300) {    return NextResponse.json({ error: 'Webhook timestamp expired' }, { status: 401 });  }  // Verify HMAC-SHA256  const expectedSig = crypto    .createHmac('sha256', secretKey)    .update(`${timestamp}.${rawBody}`)    .digest('hex');  const isValid = crypto.timingSafeEqual(    Buffer.from(receivedSig, 'utf8'),    Buffer.from(expectedSig, 'utf8')  );  if (!isValid) {    return NextResponse.json({ error: 'Signature verification failed' }, { status: 401 });  }  const payload = JSON.parse(rawBody);  console.log('Valid webhook payload:', payload.event, payload.message_id);  return NextResponse.json({ success: true });}

import express from 'express';import crypto from 'node:crypto';const app = express();// Capture raw body buffer before JSON parsingapp.use(  express.json({    verify: (req: any, _res, buf) => {      req.rawBody = buf.toString('utf8');    },  }));function verifyWebhookSignature(  rawBody: string,  signatureHeader: string,  secretKey: string,  toleranceSeconds = 300): boolean {  try {    const parts = Object.fromEntries(      signatureHeader.split(',').map((kv) => kv.trim().split('='))    );    const timestamp = parseInt(parts.t, 10);    const receivedSig = parts.v1;    if (!timestamp || !receivedSig) return false;    // 1. Replay attack prevention    const now = Math.floor(Date.now() / 1000);    if (Math.abs(now - timestamp) > toleranceSeconds) {      return false;    }    // 2. Compute expected HMAC    const expectedSig = crypto      .createHmac('sha256', secretKey)      .update(`${timestamp}.${rawBody}`)      .digest('hex');    // 3. Constant-time comparison    return crypto.timingSafeEqual(      Buffer.from(receivedSig, 'utf8'),      Buffer.from(expectedSig, 'utf8')    );  } catch {    return false;  }}app.post('/api/webhook', (req: any, res) => {  const signatureHeader = req.headers['x-aliasfleet-signature'] as string;  const secretKey = process.env.ALIASFLEET_WEBHOOK_SECRET!;  if (!signatureHeader || !verifyWebhookSignature(req.rawBody, signatureHeader, secretKey)) {    return res.status(401).json({ error: 'Invalid webhook signature' });  }  const event = req.body;  console.log(`Received email event ${event.event} for alias ${event.alias}`);  return res.status(200).json({ received: true });});

import hmacimport hashlibimport timefrom fastapi import FastAPI, Request, HTTPException, Headerapp = FastAPI()WEBHOOK_SECRET = "af_whsec_your_signing_secret_here"@app.post("/api/webhook")async def handle_webhook(    request: Request,    x_aliasfleet_signature: str = Header(None)):    if not x_aliasfleet_signature:        raise HTTPException(status_code=401, detail="Missing signature header")    # Read raw body bytes    raw_body = await request.body()    raw_text = raw_body.decode("utf-8")    # Parse t and v1    parts = dict(item.split("=") for item in x_aliasfleet_signature.split(","))    timestamp = int(parts.get("t", 0))    received_sig = parts.get("v1", "")    # Replay protection (5-minute window)    if abs(int(time.time()) - timestamp) > 300:        raise HTTPException(status_code=401, detail="Timestamp out of tolerance window")    # Compute expected signature    signed_payload = f"{timestamp}.{raw_text}".encode("utf-8")    expected_sig = hmac.new(        WEBHOOK_SECRET.encode("utf-8"),        signed_payload,        hashlib.sha256    ).hexdigest()    # Timing-safe comparison    if not hmac.compare_digest(received_sig, expected_sig):        raise HTTPException(status_code=401, detail="Invalid signature")    payload = await request.json()    return {"status": "ok", "event": payload.get("event")}

package mainimport (	"crypto/hmac"	"crypto/sha256"	"encoding/hex"	"fmt"	"io"	"math"	"net/http"	"strconv"	"strings"	"time")func VerifyWebhook(rawBody []byte, signatureHeader string, secret string) bool {	var timestamp int64	var receivedSig string	for _, part := range strings.Split(signatureHeader, ",") {		kv := strings.SplitN(strings.TrimSpace(part), "=", 2)		if len(kv) == 2 {			if kv[0] == "t" {				timestamp, _ = strconv.ParseInt(kv[1], 10, 64)			} else if kv[0] == "v1" {				receivedSig = kv[1]			}		}	}	if timestamp == 0 || receivedSig == "" {		return false	}	// 5-minute replay window	now := time.Now().Unix()	if math.Abs(float64(now-timestamp)) > 300 {		return false	}	payloadToSign := fmt.Sprintf("%d.%s", timestamp, string(rawBody))	mac := hmac.New(sha256.New, []byte(secret))	mac.Write([]byte(payloadToSign))	expectedSig := hex.EncodeToString(mac.Sum(nil))	return hmac.Equal([]byte(receivedSig), []byte(expectedSig))}

curl -X GET "https://api.aliasfleet.com/v1/webhooks/endpoints" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

{  "endpoints": [    {      "id": "wh_e0a1b2c3d4e5f6a7",      "name": "Production Ingestion Pipeline",      "url": "https://api.mycompany.com/v1/emails/webhook",      "payload_format": "parsed_json",      "is_active": true,      "failure_count": 0,      "last_triggered_at": "2026-09-14T12:00:00.000Z",      "created_at": "2026-09-01T08:30:00.000Z",      "updated_at": "2026-09-14T12:00:00.000Z"    }  ]}

curl -X GET "https://api.aliasfleet.com/v1/webhooks/endpoints/wh_e0a1b2c3d4e5f6a7" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

{  "endpoint": {    "id": "wh_e0a1b2c3d4e5f6a7",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Production Ingestion Pipeline",    "url": "https://api.mycompany.com/v1/emails/webhook",    "secret_key": "af_whsec_9f83a21b4c7d0e9a8b7c6d5e4f3a2b1c8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b",    "payload_format": "parsed_json",    "is_active": true,    "failure_count": 0,    "last_triggered_at": "2026-09-14T12:00:00.000Z",    "created_at": "2026-09-01T08:30:00.000Z",    "updated_at": "2026-09-14T12:00:00.000Z"  }}

curl -X POST "https://api.aliasfleet.com/v1/webhooks/endpoints" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "name": "Production Ingestion Pipeline",    "url": "https://api.mycompany.com/v1/emails/webhook",    "payload_format": "parsed_json",    "is_active": true  }'

{  "message": "Webhook endpoint created successfully",  "endpoint": {    "id": "wh_e0a1b2c3d4e5f6a7",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Production Ingestion Pipeline",    "url": "https://api.mycompany.com/v1/emails/webhook",    "secret_key": "af_whsec_9f83a21b4c7d0e9a8b7c6d5e4f3a2b1c8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b",    "payload_format": "parsed_json",    "is_active": true,    "failure_count": 0,    "last_triggered_at": null,    "created_at": "2026-09-14T15:00:00.000Z",    "updated_at": "2026-09-14T15:00:00.000Z"  }}

curl -X PATCH "https://api.aliasfleet.com/v1/webhooks/endpoints/wh_e0a1b2c3d4e5f6a7" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "name": "Updated Ingestion Pipeline",    "is_active": true  }'

{  "message": "Webhook endpoint updated successfully",  "endpoint": {    "id": "wh_e0a1b2c3d4e5f6a7",    "name": "Updated Ingestion Pipeline",    "url": "https://api.mycompany.com/v1/emails/webhook",    "payload_format": "parsed_json",    "is_active": true,    "failure_count": 0,    "last_triggered_at": "2026-09-14T12:00:00.000Z",    "created_at": "2026-09-01T08:30:00.000Z",    "updated_at": "2026-09-14T15:30:00.000Z"  }}

curl -X POST "https://api.aliasfleet.com/v1/webhooks/endpoints/wh_e0a1b2c3d4e5f6a7/rotate-secret" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json"

{  "message": "Webhook secret rotated successfully",  "secret_key": "af_whsec_8f93a21b4c7d0e9a8b7c6d5e4f3a2b1c8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b",  "endpoint": {    "id": "wh_e0a1b2c3d4e5f6a7",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Production Ingestion Pipeline",    "url": "https://api.mycompany.com/v1/emails/webhook",    "payload_format": "parsed_json",    "is_active": true,    "secret_key": "af_whsec_8f93a21b4c7d0e9a8b7c6d5e4f3a2b1c8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b",    "failure_count": 0,    "last_triggered_at": "2026-09-14T12:00:00.000Z",    "created_at": "2026-08-25T12:00:00.000Z",    "updated_at": "2026-09-14T15:35:00.000Z"  }}

curl -X DELETE "https://api.aliasfleet.com/v1/webhooks/endpoints/wh_e0a1b2c3d4e5f6a7" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

{  "success": true,  "message": "Webhook endpoint deleted successfully"}

curl -X POST "https://api.aliasfleet.com/v1/webhooks/test" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "endpoint_id": "wh_e0a1b2c3d4e5f6a7",    "url": "https://api.mycompany.com/v1/emails/webhook",    "payload_format": "parsed_json"  }'

{  "success": true,  "status_code": 200,  "response_time_ms": 142,  "response_body": "{\"received\": true}",  "signature_header": "t=1756972800,v1=9f83a21b4c7d0e9a8b7c6d5e4f3a2b1c8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b",  "dispatched_payload": "{\"event\":\"email.received\",\"timestamp\":\"2026-09-14T15:00:00.000Z\",\"message_id\":\"<test_e0a1b2c3@aliasfleet.com>\",\"alias\":\"test-alias@user.aliasfleet.com\",\"sender\":{\"address\":\"billing@example.com\",\"name\":\"Example Billing\"},\"recipient\":\"test-alias@user.aliasfleet.com\",\"subject\":\"[Test] AliasFleet Webhook Dispatch Simulator\"}",  "signing_secret": "af_whsec_9f83a21b4c7d0e9a8b7c6d5e4f3a2b1c8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b"}

curl -X GET "https://api.aliasfleet.com/v1/webhooks/deliveries?limit=10&status=failed" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

{  "deliveries": [    {      "id": "whd_d0a1b2c3d4e5f6a7",      "webhook_endpoint_id": "wh_e0a1b2c3d4e5f6a7",      "rule_id": "rule_a1b2c3d4e5f67a8b",      "status_code": 200,      "response_time_ms": 94,      "error_message": null,      "payload_snippet": {        "event": "email.received",        "recipient": "orders.749@afinbox.com",        "subject": "Monthly Subscription Invoice"      },      "created_at": "2026-09-14T15:32:10.000Z"    }  ],  "pagination": {    "total": 48,    "total_unfiltered": 120,    "limit": 10,    "offset": 0  },  "retention": {    "days": 30,    "plan": "business",    "is_business": true  }}

curl -X GET "https://api.aliasfleet.com/v1/webhooks/deliveries/export?format=csv&status=failed" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -o "webhook_failed_deliveries.csv"