Gmail to Webhook

Why Route Gmail Emails to a Webhook?

Gmail is Google's free consumer and business email service with over 1.8 billion active users worldwide. While Gmail is a capable email platform, its native tooling for programmatic automation was not built for developers who need structured, reliable data delivery to backend systems.

The native approach — Gmail Pub/Sub API — introduces significant operational overhead. You need to manage credentials, poll or maintain persistent connections, and write custom parsing logic for every message field you care about. When your team is moving fast, that friction adds up to hours of maintenance per integration.

JsonHook eliminates that overhead by accepting inbound mail on your behalf and immediately firing a structured JSON payload to any HTTPS endpoint you specify. The email is parsed, attachments are base64-encoded, and headers are normalised — so your webhook handler can focus entirely on business logic rather than MIME parsing.

Below are the core benefits of routing your Gmail messages through JsonHook instead of relying on the native alternative:

• Limitation avoided: Gmail's Pub/Sub API requires a Google Cloud project, OAuth credentials, and a persistent Pub/Sub subscriber — significant infrastructure for a simple automation.
• Limitation avoided: The Gmail API does not push structured JSON; you receive raw RFC 2822 MIME data that your code must parse.
• Limitation avoided: Gmail's native Pub/Sub push notifications do not include retry logic — if your endpoint is down, the event is lost.
• Zero-polling architecture: JsonHook pushes to your endpoint the moment mail arrives — no long-running background jobs needed.
• Automatic attachment handling: PDFs, images, and other file types are extracted, base64-encoded, and included in the JSON payload with their original MIME type.
• Retry with exponential back-off: If your endpoint is temporarily unavailable, JsonHook retries automatically — something the Gmail Pub/Sub API does not do natively.
• Webhook signatures for security: Every delivery includes an HMAC-SHA256 signature header so you can verify the payload originated from JsonHook.

Whether you are building a support-ticket ingestion pipeline, a lead-capture workflow, or an automated document processor, JsonHook gives you a consistent, typed interface to Gmail messages without the fragility of raw SMTP or polling-based API integrations.

How to Forward Gmail to JsonHook

Getting Gmail emails delivered to your webhook takes about five minutes. The process has two parts: creating a JsonHook address via the API, and configuring Gmail to forward a copy of each incoming message to that address.

1. Open Gmail and click the gear icon, then See all settings.
2. Navigate to Forwarding and POP/IMAP and click Add a forwarding address.
3. Enter your JsonHook inbound address (e.g. [email protected]) and confirm ownership via the verification email sent to that address.
4. Set the forwarding option to Forward a copy of incoming mail to your JsonHook address and save changes. Optionally create a filter under Filters and Blocked Addresses to forward only specific senders or subjects.

Once forwarding is active, every email that arrives in your Gmail inbox (or matches your filter) will be relayed to your JsonHook address, parsed, and delivered to your endpoint as a JSON payload within seconds.

You can create your JsonHook inbound address with a single curl command. Replace YOUR_API_KEY with the key from your dashboard and set webhookUrl to your endpoint:

curl -X POST https://jsonhook.com/api/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Gmail inbound",
    "webhookUrl": "https://your-app.example.com/webhooks/email",
    "secret": "a-random-signing-secret"
  }'

The response includes your unique @in.jsonhook.com address. Copy that address and paste it into the forwarding field in your Gmail settings. That is all the infrastructure you need to stand up.

Gmail vs Gmail Pub/Sub API

When developers first explore email-to-webhook automation they typically discover Gmail Pub/Sub API — the official programmatic route provided by Google. The table below shows how it compares to using JsonHook as an intermediary.

The native approach through Gmail Pub/Sub API requires you to set up OAuth credentials or API keys, maintain a long-running listener or polling job, write your own MIME parser, and implement your own retry queue. Any one of those steps can become a reliability bottleneck in production.

JsonHook handles all of that infrastructure on your behalf. You get a single HTTPS webhook call with a predictable JSON schema every time a Gmail email arrives — no polling, no credential rotation, no MIME parsing, and no bespoke retry code to maintain.

JSON Payload Example

When a Gmail email is forwarded to your JsonHook address and delivered to your endpoint, the request body looks like the following. All fields are consistently present; optional fields such as htmlBody and attachments are included when the source message contains them.

{
  "id": "msg_01j8xkr4p2vn3q7w",
  "receivedAt": "2026-03-15T14:32:07.412Z",
  "from": {
    "name": "Alice Smith",
    "address": "[email protected]"
  },
  "to": [
    {
      "name": "",
      "address": "[email protected]"
    }
  ],
  "subject": "Your Gmail message subject here",
  "textBody": "Plain-text content of the email body.",
  "htmlBody": "<div>HTML version of the email body.</div>",
  "headers": {
    "message-id": "<[email protected]>",
    "x-mailer": "Google",
    "mime-version": "1.0"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 84234,
      "content": "JVBERi0xLjQK..."
    }
  ],
  "spf": "pass",
  "dkim": "pass"
}

The id field is a unique, stable identifier you can use for idempotent processing. The spf and dkim fields reflect the authentication results JsonHook observed when receiving the message, which you can use to enforce additional trust policies in your handler.

Attachment content is standard base64. Decode it with a single call in any language — Buffer.from(att.content, 'base64') in Node.js, base64.b64decode(att.content) in Python, and so on.

Here is a minimal Node.js webhook handler for incoming Gmail messages:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhooks/email', (req, res) => {
  const sig = req.headers['x-jsonhook-signature'] as string;
  const body = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.JSONHOOK_SECRET!)
    .update(body)
    .digest('hex');
  if (sig !== expected) return res.status(401).send('Invalid signature');

  const { from, subject, textBody } = req.body;
  console.log(`Gmail message from ${from.address}: ${subject}`);
  // Process the email...
  res.status(200).send('ok');
});

app.listen(3000);

Common Gmail to Webhook Use Cases

Gmail is the world's most widely used email service, which means it is often the channel through which personal project notifications, developer alerts, and consumer-facing workflows arrive. Routing Gmail messages through a webhook unlocks automation that would otherwise require manual checking or fragile IMAP polling.

• Personal project alerts: Forward Github notification emails, CI/CD failure alerts, or server monitoring notices from Gmail directly into a Slack channel or a custom alerting dashboard via webhook.
• Form-to-CRM pipelines: Many web form services send confirmation copies to a Gmail address. Forward those into JsonHook to automatically create or update leads in your CRM without a Zapier subscription.
• Receipt and invoice parsing: Automatically extract purchase totals, vendor names, and invoice numbers from email receipts forwarded from Gmail into an expense-tracking or bookkeeping application.
• Two-factor code relay: Forward OTP or verification emails to a webhook that stores the latest code in a cache, enabling automated end-to-end testing of sign-up and login flows.