Webhooks

A webhook is an HTTPS endpoint of yours that the mail service calls when something happens in your account's inboxes: a message arrives, or an inbox expires. Use it when you cannot keep a WebSocket open, for example in a server that processes sign-up emails.

Webhooks are a premium feature: a premium account can register up to 20 endpoints. Other tiers get 403 tier_required. Webhooks are managed from a logged-in session, not with an API key. Only inboxes owned by the account trigger webhooks; inboxes of an anonymous session never do.

Event types

Delivery

Each delivery is an HTTPS POST with Content-Type: application/json and User-Agent: grrla-webhooks/1, and these headers:

The body has four fields: id (the delivery id), event, created_at (when the event happened, RFC 3339) and data.

{
  "id": "019a2f61-4a7b-7c90-a1b2-c3d4e5f60718",
  "event": "message.new",
  "created_at": "2026-10-26T08:05:12.481+00:00",
  "data": {
    "inbox_id": "019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b",
    "message_id": "019a2f61-3e5a-7b12-8c4d-6e8f0a2b4c6d",
    "received_at": "2026-10-26T08:05:12+00:00",
    "from_addr": "noreply@example.com",
    "from_name": "Example",
    "subject": "Your sign-in code",
    "snippet": "Your code is 481920. It expires in 10 minutes.",
    "size_bytes": 5821,
    "has_attachments": false
  }
}

{
  "id": "019a2f9c-0d1e-7f20-b3c4-d5e6f7081920",
  "event": "inbox.expired",
  "created_at": "2026-10-26T09:00:30.002+00:00",
  "data": {
    "inbox_id": "019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b",
    "expires_at": "2026-10-26T09:00:00+00:00"
  }
}

A webhook body carries only the summary. Fetch the message itself with GET /v1/messages/:id, using a session token or an API key.

Retries and auto-disable

• Any 2xx response acknowledges the delivery. Anything else, including a timeout, is a failure.
• Each attempt has a 10-second budget. Redirects are not followed and count as failures.
• A failed delivery is retried with exponential backoff (5 s, 10 s, 20 s, and so on), up to 8 attempts in total.
• After 20 consecutive failures the endpoint is disabled: enabled becomes false and disabled_reason says why. Deliveries stop until you call POST /v1/webhooks/:id/enable.
• The URL must use https, must not contain credentials or a fragment, and must resolve to public addresses. Private, loopback, link-local and similar ranges are refused: at registration for a literal IP or localhost, and after DNS resolution at every delivery. The connection is pinned to the addresses that passed the check.
• last_attempt_at, last_status and last_error on the endpoint show the result of the latest attempt.

Verifying signatures

When you create a webhook, the response contains its secret once, as 64 hex characters. The signature is

v1 = hex(HMAC-SHA256(key, "<t>.<raw body>"))

where key is the hex-decoded secret (32 bytes) and t is the timestamp from the same header. To verify a delivery:

1. Parse t and v1 from X-Grrla-Signature.
2. Reject the delivery if t is more than a few minutes from your clock.
3. Compute the HMAC over the raw request bytes, exactly as received. Do not parse and re-serialise the JSON first.
4. Compare with v1 in constant time.

Each retry is signed again with a new t.

import hashlib
import hmac
import time


def verify(secret_hex: str, header: str, body: bytes, tolerance_secs: int = 300) -> bool:
    try:
        fields = dict(part.split("=", 1) for part in header.split(","))
        t = int(fields["t"])
        received = fields["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance_secs:
        return False
    key = bytes.fromhex(secret_hex)
    expected = hmac.new(key, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)


# Flask example
# @app.post("/hooks/mail")
# def hook():
#     if not verify(SECRET, request.headers.get("X-Grrla-Signature", ""), request.get_data()):
#         abort(401)
#     event = request.get_json()
#     ...
#     return "", 204

The webhook model

The secret is never returned after creation.

Create a webhook

curl https://mail.nullnet.sh/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/mail", "events": ["message.new"]}'

{
  "secret": "9f2c4e6a8b0d1f3e5a7c9b1d3f5e7a9c0b2d4f6e8a1c3e5b7d9f0a2c4e6b8d0f",
  "webhook": {
    "id": "019a2f70-2b4c-7d6e-8f90-a1b2c3d4e5f6",
    "url": "https://example.com/hooks/mail",
    "events": ["message.new"],
    "inbox_id": null,
    "enabled": true,
    "failures": 0,
    "created_at": "2026-10-26T08:00:00Z",
    "last_attempt_at": null,
    "last_status": null,
    "last_error": null,
    "disabled_reason": null
  }
}

List webhooks

curl https://mail.nullnet.sh/v1/webhooks \
  -H "Authorization: Bearer {token}"

Get a webhook

curl https://mail.nullnet.sh/v1/webhooks/019a2f70-2b4c-7d6e-8f90-a1b2c3d4e5f6 \
  -H "Authorization: Bearer {token}"

Delete a webhook

curl -X DELETE https://mail.nullnet.sh/v1/webhooks/019a2f70-2b4c-7d6e-8f90-a1b2c3d4e5f6 \
  -H "Authorization: Bearer {token}"

Send a test delivery

curl -X POST https://mail.nullnet.sh/v1/webhooks/019a2f70-2b4c-7d6e-8f90-a1b2c3d4e5f6/test \
  -H "Authorization: Bearer {token}"

{ "delivery_id": "019a2f71-5c6d-7e8f-90a1-b2c3d4e5f607" }

Re-enable a webhook

curl -X POST https://mail.nullnet.sh/v1/webhooks/019a2f70-2b4c-7d6e-8f90-a1b2c3d4e5f6/enable \
  -H "Authorization: Bearer {token}"