Real-Time Event Streams

Webhooks & HMAC SHA-256 Signatures

Envelark dispatches outbound HTTPS webhooks to your application whenever an email is received, outbound messages are delivered, Payeny invoices settle, or custom automation pipelines execute.

1. Emitted Event Types

The following event types are emitted by domain services in the platform:

Event Identifier Origin Service Description
message.received MailboxService / ImapService Dispatched immediately upon parsing an inbound email, normalizing thread associations, and extracting attachments.
message.sent RelayService Dispatched when a message or transactional email is successfully delivered through the SMTP/relay infrastructure.
billing.invoice_settled PayenyService Dispatched when an inline invoice is marked paid or credit refill payment clears successfully.
postcard.created PrintMailService Dispatched when a physical postcard with tracked QR code is queued for automated print fulfillment.
automation.webhook AutomationService Dispatched when an automation workflow rule matches an inbound message and triggers an external webhook step.

2. Webhook Payload Structure

Every delivery includes metadata headers: X-Envelark-Signature: sha256=<hash>, X-Envelark-Event: <event_type>, and User-Agent: Envelark-Webhook-Engine/1.0.

{
  "event": "message.received",
  "api_version": "2026-09-01",
  "timestamp": "2026-10-21T14:32:00+00:00",
  "data": {
    "message_id": "msg_8f1a2b3c4d5e",
    "mailbox_id": 2,
    "mailbox_email": "support@example.com",
    "from": "customer@client.example.com",
    "from_name": "Elena Rostova",
    "subject": "Question regarding CSV export permissions",
    "snippet": "Hi support team, we are configuring our shared inboxes...",
    "stream": "human",
    "has_attachments": false,
    "received_at": "2026-10-21T14:31:58+00:00"
  }
}

3. Signature Verification

To verify that payloads originate from Envelark and have not been tampered with in transit, compute an HMAC SHA-256 hash of the exact raw request body using your app's webhook_secret. Compare using constant-time string comparison.

PHP Verification Snippet

<?php
// 1. Read raw input body (never use $_POST)
$rawBody = file_get_contents('php://input');

// 2. Fetch signature header
$signatureHeader = $_SERVER['HTTP_X_ENVELARK_SIGNATURE'] ?? '';

// 3. Your secret from Envelark Developer Portal
$webhookSecret = getenv('ENVELARK_WEBHOOK_SECRET') ?: 'YOUR_WEBHOOK_SECRET';

// 4. Compute expected signature
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);

// 5. Constant-time comparison
if (!hash_equals($expected, $signatureHeader)) {
    http_response_code(401);
    exit('Invalid webhook signature');
}

// 6. Safe to parse and process event
$event = json_decode($rawBody, true);
http_response_code(200);
echo json_encode(['received' => true]);

Node.js / Express Verification Snippet

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

// Capture raw body for signature verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-envelark-signature'] || '';
  const secret = process.env.ENVELARK_WEBHOOK_SECRET || 'whsec_YOUR_SECRET'; // Replace 'YOUR_WEBHOOK_SECRET' with your signing secret

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)
    .digest('hex');

  const sigBuffer = Buffer.from(signature, 'utf8');
  const expBuffer = Buffer.from(expected, 'utf8');

  if (sigBuffer.length !== expBuffer.length || !crypto.timingSafeEqual(sigBuffer, expBuffer)) {
    return res.status(401).send('Invalid webhook signature');
  }

  const { event, data } = req.body;
  console.log(`Processing ${event}:`, data);
  res.status(200).json({ received: true });
});

4. Delivery Timeout & Retry Behavior

  • Connect Timeout: 2 seconds. Total transfer timeout: 4 seconds.
  • Success Status: Any HTTP 2xx code (e.g. 200 OK, 204 No Content) is logged as a successful delivery.
  • Failure & Replay: Non-2xx responses and connection timeouts are logged in the webhook_deliveries ledger with full response status, error snippet, and latency in milliseconds. Deliveries can be manually replayed with 1 click from the Developer Portal.