Skip to main content

Webhooks Operations

This operations page covers the production posture for webhook endpoints. For event semantics and payload concepts, read Webhooks.

Endpoint contract​

Your webhook endpoint should:

  • Accept HTTPS POST requests.
  • Verify the Mailtarget signature before trusting the payload.
  • Return 2xx quickly after enqueueing work.
  • Process events asynchronously.
  • Deduplicate repeated deliveries.

Idempotency key​

Use a stable event identifier if Mailtarget includes one. If not, compute a key from:

transmissionId + event + timestamp + recipient

Store that key under a unique constraint before doing side effects.

Retry behavior​

Webhook delivery can repeat when your endpoint times out or returns a non-2xx response. Treat every event as at-least-once delivery.

Do not use webhook retries as your main queue. Acknowledge fast, then process in your own queue where you control retry limits and alerting.