Webhook integration guide

1. A connected Gmail account receives a message, and Google pushes it to AtEmail.
2. AtEmail syncs the message and evaluates your active criteria against it.
3. For each rule that matches, the webhooks linked to that rule are queued for delivery.
4. AtEmail generates an AI summary of the message, if it does not already have one.
5. It POSTs the message and summary to your URL, signed, and records the outcome in the delivery log.

Everything below describes that final POST and what your endpoint has to do with it.

1. In Settings → Webhooks, add your endpoint URL and a signing secret. Generate a long random secret; it is the only thing proving a request came from us.
2. In Settings → Email Criteria, create a rule and link it to that webhook.
3. Deploy a receiver using one of the samples in Verify the signature, then send yourself a matching email and watch it arrive in Settings → Logs.

Every delivery is a POST with a JSON body and these headers:

The signature is HMAC-SHA256 of the raw request body, using the webhook’s secret, encoded as lowercase hex. Compute it over the bytes you received, before any JSON parsing: re-serialising the body changes it and the signature will not match. Compare in constant time, and reject anything that fails.

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

const app = express();
const SECRET = process.env.ATEMAIL_WEBHOOK_SECRET;

function verify(rawBody, signature) {
  if (!signature) return false;
  const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(signature, 'hex'),
    );
  } catch {
    return false;             // malformed signature header
  }
}

// Register BEFORE express.json() so the raw body is still available.
app.post(
  '/api/atemail/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8');

    if (!verify(rawBody, req.headers['x-atemail-signature'])) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const { email } = JSON.parse(rawBody);

    // Answer first, work afterwards: you have 30 seconds.
    res.status(200).json({ received: true, email_id: email.id });

    queue.add(() => handleEmail(email));
  },
);

app.listen(3000);

<?php
declare(strict_types=1);

const ATEMAIL_WEBHOOK_SECRET = 'YOUR_WEBHOOK_SECRET';

$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ATEMAIL_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $rawBody, ATEMAIL_WEBHOOK_SECRET);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$payload = json_decode($rawBody, true);
$email   = $payload['email'] ?? [];

// Acknowledge, then process out of band.
http_response_code(200);
echo json_encode(['received' => true, 'email_id' => $email['id'] ?? null]);

handle_atemail_email($email);

// Cloudflare Worker, Deno, or any WebCrypto runtime.
export default {
  async fetch(request, env) {
    const rawBody = await request.text();
    const signature = request.headers.get('x-atemail-signature') ?? '';

    const key = await crypto.subtle.importKey(
      'raw',
      new TextEncoder().encode(env.ATEMAIL_WEBHOOK_SECRET),
      { name: 'HMAC', hash: 'SHA-256' },
      false,
      ['sign'],
    );
    const mac = await crypto.subtle.sign(
      'HMAC',
      key,
      new TextEncoder().encode(rawBody),
    );
    const expected = [...new Uint8Array(mac)]
      .map((b) => b.toString(16).padStart(2, '0'))
      .join('');

    if (expected !== signature) {
      return new Response('Invalid signature', { status: 401 });
    }

    const { email } = JSON.parse(rawBody);
    await handleEmail(email);

    return Response.json({ received: true, email_id: email.id });
  },
};

Any 2xx status counts as success. Reply within 30 seconds; anything slower is treated as a failure and retried. Acknowledge first and do the real work afterwards, in a queue or background job.

{
  "received": true,
  "email_id": "clx123abc"
}

Because a slow response can be retried after your system already handled it, the same message can arrive more than once. Make your handler idempotent by keeping the email.id values you have processed and ignoring repeats.

A rule decides which emails reach your endpoint. Each filter is a comma-separated list, and matching is case-insensitive.

Filters you leave empty are ignored. A rule with several filters set requires all of them to match, so start broad and narrow it once you see real deliveries in the log.

Settings → Logs lists every attempt for a webhook with its status, attempt count, a snippet of your response and any error. Statuses are PENDING, SUCCESS, RETRYING and FAILED. This is the first place to look when a message did not arrive: a rule that never matched shows no attempt at all, while a rejected signature shows an attempt with a 401.

• Accept POST with a JSON body, and use HTTPS in production.
• Be reachable on the public internet.
• Return 2xx within 30 seconds.
• Deduplicate on email.id.

Everything in the dashboard is also available over the API, for provisioning webhooks and rules programmatically. Authenticate with a bearer token and send JSON.

POST /api/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "connectedAccountId": "<account-id>",
  "name": "Production CRM",
  "url": "https://your-system.com/api/atemail/webhook",
  "secret": "whsec_your_random_secret_here",
  "headers": { "X-Client-Account": "billing@yourteam.com" }
}

POST /api/criteria
Authorization: Bearer <token>
Content-Type: application/json

{
  "connectedAccountId": "<account-id>",
  "name": "Client invoices",
  "fromFilter": "billing@acme.com",
  "subjectFilter": "invoice, payment due",
  "webhookIds": ["<webhook-id>"]
}

The full reference, including every parameter, is published by the API itself at /api-docs.

Nothing arrives and the log is empty

No rule matched. Check the filters against the real sender and subject, confirm the rule is active, and confirm it is linked to the webhook.

Every attempt returns 401

The signature check is failing. The usual cause is verifying a re-serialised body instead of the raw one, or a mismatch between the secret in AtEmail and the one your code reads.

Deliveries time out

Your handler is doing the work before replying. Return 2xx immediately and process the message in the background.

The same email arrives repeatedly

A slow or failed response triggered a retry. Deduplicate on email.id.

aiSummary is null

Summary generation failed for that message. The delivery still happens, so fall back to email.snippet.