Webhooks
Receive real-time signed HTTP events for email deliveries, opens, link clicks, bounces, and inbound replies.
Webhooks allow your application to react in real-time when emails are delivered, opened, clicked, bounced, or replied to by recipients.
Supported Event Types
- email.delivered: The recipient's mail provider accepted and queued the message.
- email.opened: The recipient viewed the email (tracking pixel loaded).
- email.clicked: The recipient clicked an authenticated link inside the body.
- email.bounced: The message was rejected due to an invalid mailbox or server block.
- email.complained: The recipient clicked 'Mark as Spam' in their mail client.
- email.received: A new two-way inbound message or reply arrived in your mailbox.
Handling Webhook Events
Create an API route in Next.js or swift-rust to handle incoming event payloads:
app/api/webhooks/mail/route.ts
import { NextResponse } from "next/server";
export async function POST(req: Request) {
const payload = await req.json();
const { event, data } = payload;
switch (event) {
case "email.delivered":
console.log(\`Email \${data.email_id} was successfully delivered to \${data.to}\`);
break;
case "email.bounced":
console.warn(\`Email \${data.email_id} bounced. Reason: \${data.bounce_message}\`);
break;
case "email.received":
console.log(\`Received new thread reply from \${data.from}: \${data.subject}\`);
break;
}
return NextResponse.json({ received: true });
}Signature Verification
Every webhook request includes a cryptographic signature in the headers so you can verify that the payload genuinely originated from Multivrs:
lib/verify-webhook.ts
import crypto from "node:crypto";
function verifyWebhookSignature(payloadString: string, signature: string, secret: string): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(payloadString)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}Automatic Retries with Exponential Backoff
If your endpoint returns a non-2xx status code or times out, Multivrs Mail retries delivery with exponential backoff over a 72-hour window.