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
2xxcode (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_deliveriesledger with full response status, error snippet, and latency in milliseconds. Deliveries can be manually replayed with 1 click from the Developer Portal.