Channels
Outbound Webhooks
Receive real-time HTTP delivery receipts, bounce notifications, and HMAC cryptographic signature verification.
Outbound Webhooks
Configure webhook endpoints in the GNS Console to receive immediate delivery receipts, delivery failures, and open tracking events.
1. Webhook Payload Structure
When an event occurs, GNS sends an HTTP POST to your configured webhook URL:
Response200 Event Payload
{
"event": "notification.delivered",
"id": "evt_01J7K3X9AB0C1D2E3F4G",
"timestamp": "2026-09-13T13:00:00Z",
"data": {
"notification_id": "notif_01J7K3X9AB0C1D2E3F4G5H6J7K",
"channel": "email",
"recipient": "alex@example.com",
"status": "delivered",
"attempts": 1,
"smtp_response": "250 2.0.0 Ok: queued as 4N8Z9q"
}
}2. Signature Verification (X-GNS-Signature)
Every webhook request includes an X-GNS-Signature header containing an HMAC-SHA256 signature computed using your webhook signing secret:
X-GNS-Signature: t=1789314000,v1=9a8b7c6d5e4f3a2b1c0d...Verification Example (Node.js / TypeScript)
import crypto from 'crypto';
function verifyGnsWebhook(
payloadRaw: string,
signatureHeader: string,
secret: string
): boolean {
const parts = signatureHeader.split(',');
const timestamp = parts.find((p) => p.startsWith('t='))?.slice(2);
const signature = parts.find((p) => p.startsWith('v1='))?.slice(3);
if (!timestamp || !signature) return false;
const signedPayload = `${timestamp}.${payloadRaw}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}