How to Forward Gmail to a Webhook

Overview

Forwarding Gmail to a webhook lets you build automations that react to emails in your Gmail inbox without polling the Gmail API or setting up OAuth. Instead, Gmail's built-in forwarding feature sends matching emails to your JsonHook inbound address, which then delivers them as JSON to your webhook endpoint.

This approach is simpler than using the Gmail API because:

• No OAuth flow — no user authorization, no token refresh
• No polling — Gmail pushes to JsonHook which pushes to you
• No Gmail-specific SDK — your handler only speaks standard HTTP JSON
• Works alongside your normal Gmail usage — forwarding copies emails, not moves them

You can forward all Gmail messages or use Gmail filters to forward only specific messages (from specific senders, matching specific subject patterns, etc.).

Prerequisites

What you need:

• A Gmail account you want to forward from
• A JsonHook inbound address and webhook endpoint
• Gmail Settings access (not available in some Google Workspace accounts where admins restrict forwarding)

Step-by-Step Instructions

Forward Gmail messages to your webhook:

1. Create a JsonHook inbound address for Gmail forwarding with your webhook URL.
2. In Gmail, add a forwarding address:
   • Go to Gmail → Settings → See all settings → Forwarding and POP/IMAP
   • Click "Add a forwarding address" and enter your JsonHook address (e.g., [email protected])
   • Gmail will send a verification email to your JsonHook address
3. Verify the forwarding address. Check your JsonHook delivery log — the verification email from Gmail will appear as a webhook delivery. Find the verification link in the textBody field and open it in your browser to confirm the forwarding address.
4. Configure forwarding rules. Either enable forwarding for all messages, or create Gmail filters (Settings → Filters and Blocked Addresses) to forward only specific emails.
5. Test the pipeline by sending an email to your Gmail address and confirming it appears in your JsonHook delivery log and reaches your webhook handler.

Code Example

Webhook handler that processes forwarded Gmail messages and creates Slack notifications:

import express from "express";
import crypto from "crypto";
import fetch from "node-fetch";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/gmail", async (req, res) => {
  const sig = req.headers["x-jsonhook-signature"] as string;
  const expected = crypto
    .createHmac("sha256", process.env.JSONHOOK_SECRET!)
    .update(req.body).digest("hex");
  if (sig !== expected) return res.sendStatus(401);

  const { email } = JSON.parse(req.body.toString());

  // Ignore Gmail's own verification emails
  if (email.from.includes("[email protected]")) {
    return res.sendStatus(200);
  }

  // Post to Slack
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `*New email from ${email.from}*
*Subject:* ${email.subject}
${(email.textBody ?? "").slice(0, 200)}`,
    }),
  });

  res.sendStatus(200);
});

app.listen(3000);

Common Pitfalls

Gmail forwarding webhook pitfalls:

• Forwarding creates a copy, not a move. Emails forwarded by Gmail remain in your Gmail inbox. If you want them archived, add a Gmail filter action to archive matching emails after forwarding.
• Gmail wraps forwarded messages. When Gmail forwards an email, the original message is attached as an message/rfc822 attachment or appended to the body. The from field in the JsonHook payload will be the forwarder's address, not the original sender. Look in the textBody for "Forwarded message" headers to get the original sender.
• Verification email needs manual handling. When you add the forwarding address in Gmail, Gmail sends a verification code. Your webhook handler will receive this. Do not try to auto-verify it programmatically — open the confirmation link in your browser from the delivery log.
• Forwarding limits in Google Workspace. Some Google Workspace administrators restrict email forwarding to external addresses. Check with your admin before setting up cross-domain forwarding.
• Loop prevention. If your webhook sends a reply to the original sender and that reply arrives in your Gmail inbox, Gmail may forward it again. Use email.messageId for deduplication to break any forwarding loops.