Webhooks

What arrives

POST /your/endpoint HTTP/1.1
content-type: application/json
user-agent: Posthaste-Webhooks/1.0
posthaste-signature: t=1760000000,v1=6f1b0a…
posthaste-delivery-id: evt_Nc7HrQ8T2Sf9pXbAZLm3kQ
posthaste-attempt: 1

{
  "id": "evt_Nc7HrQ8T2Sf9pXbAZLm3kQ",
  "type": "bounced",
  "createdAt": "2026-08-18T06:40:11.902Z",
  "data": {
    "messageId": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ",
    "detail": { "smtp_code": 550, "diagnostic": "5.1.1 No such user here" }
  }
}

data.detail on accepted

For a message sent immediately, the accepted event’s detail always carries source — 'api' or 'smtp' — depending on whether the message came in through POST /v1/emails or the SMTP relay. When the message carried attachments, the same detail also carries an attachments array: metadata only, never content, one entry per file.

{
  "id": "evt_Nc7HrQ8T2Sf9pXbAZLm3kQ",
  "type": "accepted",
  "createdAt": "2026-08-22T09:12:03.441Z",
  "data": {
    "messageId": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ",
    "detail": {
      "to_domain": "example.com",
      "from_domain": "yourdomain.com",
      "source": "smtp",
      "attachments": [
        {
          "filename": "invoice.pdf",
          "content_type": "application/pdf",
          "size_bytes": 84213,
          "sha256": "9f2c1b7e4a3d…"
        }
      ]
    }
  }
}

# "attachments" is omitted entirely when the message had none — never an
# empty array.

A scheduled send splits accepted in two

A message you scheduled does not get an accepted event at all when you send it. Instead source, the domains and any attachments array — the fields above — are written on the scheduled event, alongside a scheduled_at echo. accepted is written later, on release, and its detail is deliberately thin — { scheduled: true, scheduled_at } — because the rest was already sent on scheduled and repeating it would be noise. If you key an integration off accepted alone expecting source to always be there, a scheduled send is where that assumption breaks; branch on data.detail.scheduled and readsource from the earlier scheduled event instead. See scheduling.

Headers

Event types

These thirteen are the complete set. They are the same values that appear in a message’s waybill.

Verifying the signature

The timestamp is signed with the body. Signing the body alone would be replayable for ever — anyone who captured one valid request could resend it indefinitely and it would still verify.

import express from 'express'
import { verifyWebhook, DELIVERY_ID_HEADER } from '@posthaste/sdk'

const app = express()

app.post(
  '/hooks/posthaste',
  // THE RAW BYTES. express.json() would hand you an object you cannot
  // re-serialise byte-for-byte, and the signature is over exactly what we sent.
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const result = verifyWebhook(
      req.body,                            // a Buffer
      req.get('posthaste-signature'),
      process.env.POSTHASTE_WEBHOOK_SECRET,
    )

    if (!result.valid) {
      // 'malformed_header' | 'unsupported_version' | 'timestamp_too_old'
      // | 'timestamp_in_future' | 'signature_mismatch'
      console.warn('rejected webhook', result.reason)
      return res.sendStatus(400)
    }

    const event = JSON.parse(req.body.toString('utf8'))

    // Deduplicate on the delivery id — a retry is not a second event.
    // Then acknowledge FAST and do the work elsewhere.
    enqueue(req.get(DELIVERY_ID_HEADER), event)
    return res.sendStatus(204)
  },
)

verifyWebhook from the SDK does all of the below: it parses the header by key rather than positionally, compares in constant time, and rejects a timestamp outside the tolerance in either direction. The hand-written versions are there because the API is not TypeScript-only — they implement exactly the same thing.

Retries

Any non-2xx response, a connection failure, or a timeout after 10 seconds is retried. There are seven attempts after the first, on a fixed ladder:

After the last one the delivery is marked failed and abandoned. Two responses stop delivery immediately instead: 404 and 410 Gone, because the endpoint is telling us it no longer exists and retrying for twelve hours would be rude rather than diligent.

Redirects are not followed. A customer URL that 302s to an internal address would turn our worker into an SSRF vector, and a signed payload arriving somewhere you did not configure is worse than a failed delivery. Register the final URL.

An endpoint that stops accepting anything is not disabled automatically. If yours has been gone for a while, delete it — otherwise every event on the account keeps generating deliveries that can only fail.

Register an endpoint

curl -X POST https://api.posthastemail.dev/v1/webhooks \
  -H "authorization: Bearer $POSTHASTE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/posthaste",
    "eventTypes": ["delivered", "bounced", "complained"]
  }'

# 201
# {
#   "id": "whk_4Rm8Ub2Xc6Ye0Zf1Ag3Bhk",
#   "url": "https://yourapp.com/hooks/posthaste",
#   "eventTypes": ["delivered", "bounced", "complained"],
#   "status": "active",
#   "signingSecret": "whsec_example_secret_Nc7HrQ8T2Sf3kQAZLm4jR8dMxN2pW7g"
# }
#
# signingSecret is shown ONCE and is not retrievable. Store it now.

List endpoints

Newest first, not paginated. Each row carries id, url, eventTypes, status (active or disabled) and createdAt. The signing secret is deliberately absent.

Delete an endpoint

Returns 204, or 404 not_found for an unknown id, another account’s id, or an id that is not a whk_ id. Deleting stops future deliveries; it does not cancel deliveries already queued.