Skip to main content
This integration lets you push your Mailkick email HTML to any HTTPS endpoint you control (Zapier, n8n, your own backend). Every payload is HMAC-SHA256 signed so you can verify it really comes from Mailkick.

Prerequisites

  • You need an Owner, Admin, or Editor workspace role to access integration settings.
  • An HTTPS endpoint that accepts POST requests with a JSON body.
  • The ability to read HTTP headers on your receiver to verify the signature.

Step 1: Enable the Webhook integration

  1. Open Settings → Integrations.
  2. Pick Webhook in the provider list.
  3. Click Enable Webhook Integration.

Step 2: Generate the signing secret

  1. The Webhook signing secret section appears under the success banner.
  2. Click Generate signing secret.
  3. Copy the secret (it starts with whsec_…) and store it as an environment variable in your receiver.
Treat the secret like a password. Anyone holding it can forge requests that look like they come from Mailkick.

Step 3: Set the Webhook URL on each email

  1. Open an email → Export.
  2. In the right-hand panel, paste your endpoint URL into Webhook URL (e.g. https://hooks.zapier.com/...).
  3. Click Sync to Webhook. Mailkick POSTs the signed payload to your URL.

Headers sent by Mailkick

Payload shape

  • event: currently always "sync". Future events may be added.
  • delivery_id: unique UUID per delivery. This value is part of the signed body; use it for deduplication after verifying the signature.
  • email_template_id: the Mailkick template id.
  • version_id: the snapshot version id, or null if no version exists yet.
  • subject: the email subject. May be null.
  • html: the rendered HTML, ready to send.
  • timestamp: ISO-8601 UTC timestamp when the payload was generated. For signature verification, use the Unix timestamp from the header’s t= value.

Verify the signature

  1. Take the raw request body as a UTF-8 string. Do not re-serialize it from a parsed object: JSON key ordering and whitespace must match exactly what Mailkick signed.
  2. Concatenate ${timestamp}.${rawBody}.
  3. Compute HMAC-SHA256(secret, signedString) and hex-encode the result.
  4. Compare against the v1 value from X-Mailkick-Signature using a constant-time comparison.
  5. Reject the request if the timestamp drifts from your server’s clock by more than 5 minutes (replay protection).

Node.js (Express)

Python (FastAPI)

PHP

Retries and idempotency

Mailkick retries a delivery on 5xx errors or network failures, with up to three attempts and waits of 1 second and then 4 seconds between attempts. All retries share the same delivery_id, Idempotency-Key, and X-Mailkick-Delivery UUID. After verifying the signature, use the delivery_id from the signed body to deduplicate requests. The HTTP delivery headers are not covered by the signature on their own. 4xx responses are treated as permanent errors and are not retried. Return 4xx only if you want to definitively reject the payload.

Rotate the secret

The new secret takes effect immediately when you click Rotate secret in Settings → Integrations → Webhook. There is no overlap period with the old secret. For a planned rotation, pause webhook syncs, rotate the secret in Mailkick, copy the new value to your receiver, then test a sync before resuming normal use. If the secret has leaked, rotate it immediately and update your receiver as soon as possible. A receiver still using the old secret will reject deliveries during the transition.

Troubleshooting

Signature does not match

  • Make sure you sign the raw request body, not a re-serialized JSON. Express’s req.body after express.json() is parsed, not raw: capture it via the verify callback as shown above.
  • Check that t= and v1= are read in the right order and not swapped.
  • Confirm your server clock is within 5 minutes of UTC.

412 Precondition Failed when syncing

No signing secret has been generated for the workspace. Open Settings → Integrations → Webhook and click Generate signing secret.

400 invalid_target_url

Mailkick blocks non-HTTPS targets and any hostname that resolves to a private/loopback/link-local IP (SSRF protection). Use a public HTTPS endpoint.

Lost the secret

Open Settings → Integrations → Webhook. The current secret is revealable from there for any workspace member. If it leaked, rotate it instead.