Skip to content
Splashify Pro
Email docsEmail

Webhooks

Webhooks let your app react to email lifecycle events as they happen. Send → Delivery → Open → Click → Bounce → Complaint → Reply — every state transition fires an HTTP POST to your URL with a structured JSON payload.

Two webhook surfaces

Pick whichever fits your integration:

You can use both at once. The account-level URL receives every event regardless of config set; the per-config-set destinations receive their filtered subset additionally. Most customers start with just the account-level URL and add per-config-set destinations later when they need to route per-customer.

Settings with the Webhook URL section open, the endpoint URL https://example.com/webhooks/splashify filled in and the Save webhook URL button
The account-level webhook URL in Settings

Event types fired to your webhook

These are the names the account-level webhook sends in event_type. A per-config-set destination subscribes with send, delivered, bounce, complaint, open, click, reject and delivery_delay, and receives the payload below with eventType set to Send, Delivery, Bounce and so on.

How it works

Loading diagram

  1. You create a configuration set (a logical grouping for sends).
  2. You add a webhook event destination to that config set, with the URL + secret + the event types you want.
  3. You send emails with configuration_set_name referencing that set.
  4. Every event for those sends gets POSTed to your URL, with an HMAC signature when the destination has a webhook_secret.
  5. Retries: 5xx + timeout → 3 attempts in all, 1min then 5min apart. 4xx → no retry (your URL is broken; we don't waste retries).

Set up a webhook in 3 calls

1. Create a config set

bash
curl https://api.splashifypro.com/api/v1/partner/email/configuration-sets \
  -H "Authorization: Bearer $SPLASHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "suppression_options": "BOUNCE_AND_COMPLAINT"
  }'

Save the config_set_id from the response.

2. Add a webhook destination

bash
curl https://api.splashifypro.com/api/v1/partner/email/configuration-sets/$CONFIG_SET_ID/event-destinations \
  -H "Authorization: Bearer $SPLASHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-webhook",
    "destination_type": "WEBHOOK",
    "webhook_url": "https://yourapp.com/webhooks/splashify",
    "webhook_secret": "your-shared-secret-32-chars",
    "matching_event_types": ["send", "delivered", "bounce", "complaint", "open", "click"]
  }'

Security

Store the webhook_secret somewhere your endpoint can read it (env var). The API will never echo it back — to rotate, PATCH a new value.

3. Reference the config set on send

bash
curl https://api.splashifypro.com/api/v1/partner/email/send \
  -H "Authorization: Bearer $SPLASHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome",
    "html_body": "<h1>Hi</h1>",
    "configuration_set_name": "production"
  }'

Within seconds your endpoint receives a Send event, then Delivery, etc.

Payload shape

Every event is one JSON envelope:

json
{
  "eventType": "Delivery",
  "mail": {
    "timestamp": "2026-05-03T12:34:56Z",
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "source": "[email protected]",
    "destination": ["[email protected]"]
  },
  "delivery": {
    "timestamp": "2026-05-03T12:34:57Z",
    "recipients": ["[email protected]"],
    "smtpResponse": "250 OK"
  }
}

Every event has the top-level eventType and mail fields. The event-specific payload is nested under a key matching the lowercase event type — delivery, bounce, complaint, etc.

Headers

Every POST to a per-config-set destination carries:

A destination with no webhook_secret gets no X-Splashify-Signature header, so you cannot verify its POSTs.

Account-level webhook

The URL in Settings gets a simpler body, with the fields of the event under data:

json
{
  "event_type": "email.delivered",
  "partner_id": "550e8400-e29b-41d4-a716-446655440000",
  "occurred_at": "2026-05-03T12:34:57.456Z",
  "data": {
    "event_id": "...",
    "message_id": "...",
    "recipient": "[email protected]",
    "event_at": "2026-05-03T12:34:57.123Z"
  }
}

A bounce adds bounce_type and bounce_reason to data. bounce_type is Permanent or Transient. bounce_reason is one word, as on Event Types.

These POSTs carry X-Splashify-Event (the event_type), X-Splashify-Delivery-ID and X-Splashify-Timestamp. They are not signed and are sent once, with no retry. Use a per-config-set destination when you need a signature or retries.

Quick verify in Node

javascript
import crypto from "crypto";

app.post("/webhooks/splashify", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("x-splashify-signature") || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.SPLASHIFY_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  const got = Buffer.from(signature);
  const want = Buffer.from(expected);
  if (got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString());
  // process event...
  res.status(200).end();
});

Next