SendGrid to Webhook

Why Route SendGrid Emails to a Webhook?

SendGrid is a cloud-based email delivery platform used by developers and marketers for transactional and marketing email at scale. While SendGrid 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 — SendGrid Inbound Parse — 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 SendGrid messages through JsonHook instead of relying on the native alternative:

• Limitation avoided: SendGrid Inbound Parse delivers email as multipart form-data rather than JSON, requiring custom parsing logic on your server.
• Limitation avoided: Inbound Parse requires configuring a dedicated subdomain with MX records pointing to mx.sendgrid.net, which is a DNS change that takes time to propagate and may conflict with existing records.
• Limitation avoided: SendGrid Inbound Parse does not provide webhook signatures or retry guarantees — failed deliveries are silently dropped.
• 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 SendGrid Inbound Parse 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 SendGrid messages without the fragility of raw SMTP or polling-based API integrations.

How to Forward SendGrid to JsonHook

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

1. Log in to your SendGrid account and navigate to Settings › Inbound Parse.
2. Click Add Host & URL, enter the subdomain you want to receive mail on (e.g. reply.yourdomain.com), and set the Destination URL to your JsonHook inbound SMTP address or configure a forward from your sending domain's reply-to address.
3. Alternatively, configure your application's reply-to header to point at your JsonHook inbound address instead of using SendGrid Inbound Parse entirely — this removes the need for Inbound Parse subdomain setup.
4. Test by sending a reply to an email dispatched through SendGrid and verifying that a webhook fires at your endpoint.

Once forwarding is active, every email that arrives in your SendGrid 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": "SendGrid 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 SendGrid settings. That is all the infrastructure you need to stand up.

SendGrid vs SendGrid Inbound Parse

When developers first explore email-to-webhook automation they typically discover SendGrid Inbound Parse — the official programmatic route provided by Twilio SendGrid. The table below shows how it compares to using JsonHook as an intermediary.

The native approach through SendGrid Inbound Parse 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 SendGrid email arrives — no polling, no credential rotation, no MIME parsing, and no bespoke retry code to maintain.

JSON Payload Example

When a SendGrid 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 SendGrid 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": "Twilio SendGrid",
    "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.

Python handler for SendGrid reply emails forwarded through JsonHook:

import hmac, hashlib, os
from flask import Flask, request, abort, json

app = Flask(__name__)

@app.route('/webhooks/sendgrid-replies', methods=['POST'])
def handle():
    sig = request.headers.get('X-JsonHook-Signature', '')
    body = request.get_data()
    expected = hmac.new(
        os.environ['JSONHOOK_SECRET'].encode(),
        body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)

    msg = request.json
    # Correlate reply to original campaign
    thread_id = msg.get('headers', {}).get('in-reply-to')
    print(f"Reply from {msg['from']['address']}, thread: {thread_id}")
    return 'ok', 200

Common SendGrid to Webhook Use Cases

SendGrid's Inbound Parse webhook is a well-known feature, but it requires configuring MX records, setting up a dedicated subdomain, and working with SendGrid's proprietary multipart form-data format. JsonHook offers the same capability with a simpler setup and a consistent JSON schema regardless of which email provider you use.

• Transactional reply capture: Applications that send transactional emails through SendGrid can use JsonHook to capture replies without setting up SendGrid Inbound Parse on a separate subdomain.
• Unsubscribe request processing: Forward reply-to-unsubscribe emails from your SendGrid sending domain to a webhook that immediately removes the address from your list and records the opt-out event.
• Feedback loop automation: Route spam complaint reports and delivery failure summaries that arrive via email into a webhook for automated suppression list management.
• Inbox placement monitoring: Send seed emails through SendGrid and forward the replies or bounce notifications to a JsonHook webhook to build a real-time inbox placement monitoring dashboard.