Choosing the Right HTTP Method for Your Webhook

When you create a webhook you pick an HTTP method: GET, POST, PUT, PATCH, or DELETE. The method you choose changes both where the email data lands in the request and what your receiving endpoint needs to handle.

How the method affects the request

For POST, PUT, PATCH, and DELETE the email is sent as a JSON body — identical structure regardless of which of these four you pick:

{
  "from": "sender@example.com",
  "to": "abc123xyz@email-webhook.com",
  "subject": "Your order has shipped",
  "message": "Hi Jane, your order #4521 ...",
  "attachments": [...]
}

For GET the data is URL-encoded into query parameters instead, and attachments are not forwarded:

https://your-endpoint.com/hook?from=sender%40example.com&to=abc123xyz%40email-webhook.com&subject=Your%20order%20has%20shipped&message=Hi%20Jane...&attachments=

The JSON payload structure is described in full in the Getting Started guide.

When to use each method

POST — the right default

Use POST when your handler creates a new record for each incoming email. It maps cleanly to REST convention and is the most common choice.

POST /tickets          → create a new support ticket
POST /events           → append an event to a log
POST /pipeline/trigger → kick off a processing job

PUT — upsert by identity

Use PUT when you want to create-or-replace a resource whose identity you can derive from the email. A common pattern is keying on the sender address or a value parsed from the subject.

PUT /contacts/sender@example.com   → create or update a contact record
PUT /subscriptions/abc123          → set a subscription state

PATCH — partial update

Use PATCH when the email signals that one field on an existing resource should change, rather than replacing the whole thing.

PATCH /orders/4521/status   → update only the status field of an order

DELETE — removal workflows

Use DELETE when the email is a signal to remove something — a cancellation email triggering record deletion, for example.

DELETE /subscriptions/abc123   → remove a subscription on cancellation notice

GET — simple integrations with no body

Use GET when your endpoint can't consume a request body: some serverless platforms, simple scripts, or no-code tools expose URLs that only read query parameters.

Important limitations of GET:

• Attachments are not forwarded — the attachments parameter will be empty.
• Long emails may exceed URL length limits (~2 KB in most environments) and get truncated or rejected.
• No request body is sent, so frameworks that only parse body middleware won't see the data.

For anything beyond a quick integration, prefer POST.

Quick reference

Receiving the request

Regardless of method, email-webhook always sends these headers:

Your custom headers (e.g. Authorization: Bearer <token>) are merged in on top. For guidance on using custom headers to authenticate your endpoint, see How to Authenticate Your Webhook Endpoint.