Postmark inbound webhook (platform-level)

Handles bounces, complaints, and inbound parsing sent from Postmark to Formspring. This is a server-wide integration, not per-form. The endpoint lives at POST /webhooks/postmark and is processed by App\Http\Controllers\Webhooks\PostmarkWebhookController.

Distinct from the outbound Postmark driver which sends transactional email per submission.

What it does

• Bounce events mark recipient addresses as suppressed in email_suppressions so we don't keep sending to dead addresses.
• Complaint / spam events do the same plus log a flag (a future feature can use this to alert form owners).
• Inbound parsing (optional) routes inbound email to a form-defined address into a submission - only useful if you've configured an inbound stream.

* * *

Step 1 - Configure the inbound webhook URL in Postmark

1. Sign in to https://account.postmarkapp.com/servers.
2. Open the Server you use for outbound mail (per postmark.md).
3. Default Transactional Stream (or whichever stream is sending) → Settings tab → scroll to Webhooks.
4. Set Bounce webhook: https://formspring.io/webhooks/postmark.
5. Set Spam complaint webhook: same URL.
6. Save.

For inbound parsing (optional):

1. Inbound stream (create one if absent).
2. Webhook: https://formspring.io/webhooks/postmark.

* * *

Step 2 - Configure the inbound secret in Formspring

To prevent unauthorised POSTs, Formspring validates a shared secret in the request. Set in .env:

POSTMARK_INBOUND_SECRET=<a long random string>

Then in Postmark, add the same secret to the webhook URL as a query parameter:

https://formspring.io/webhooks/postmark?secret=<the same value>

The controller (PostmarkWebhookController) validates request('secret') === config('services.postmark.inbound_secret') and 401s otherwise.

* * *

Step 3 - Verify the wiring

1. In Postmark, send a test bounce: Servers → your server → Activity → click any sent message → Send test bounce → fill in the recipient.
2. Tail the application logs.
3. Confirm a row appears in email_suppressions with the bounced address.

* * *

Where the credential lives

• Server: .env → POSTMARK_INBOUND_SECRET → config/services.php postmark.inbound_secret.
• Controller: app/Http/Controllers/Webhooks/PostmarkWebhookController.php.
• Route: routes/web.php → POST /webhooks/postmark (no CSRF token required since Postmark is the caller).
• Suppression model: app/Models/EmailSuppression.php + listener app/Listeners/SuppressMailToSuppressedAddresses.php.

* * *

Postmark webhook event types we handle

* * *

Security

• Rotate the inbound secret by generating a new value, updating .env, restarting the app, then updating each Postmark webhook URL's ?secret= query param.
• The secret is sent as a query string, which means it appears in Postmark's webhook delivery logs. That's acceptable - Postmark restricts log access to your account.
• For extra defence, add Postmark's IP allowlist to your firewall (Postmark publishes their IPs at https://postmarkapp.com/support/article/800-ips-for-firewalls).

* * *

Troubleshooting

* * *

Provider docs

• Postmark webhooks: https://postmarkapp.com/developer/webhooks/webhooks-overview
• Bounce webhook: https://postmarkapp.com/developer/webhooks/bounce-webhook
• Spam complaint webhook: https://postmarkapp.com/developer/webhooks/spam-complaint-webhook
• Inbound webhook: https://postmarkapp.com/developer/webhooks/inbound-webhook