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.

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
- You create a configuration set (a logical grouping for sends).
- You add a webhook event destination to that config set, with the URL + secret + the event types you want.
- You send emails with
configuration_set_namereferencing that set. - Every event for those sends gets POSTed to your URL, with an
HMAC signature when the destination has a
webhook_secret. - 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
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
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
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:
{
"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:
{
"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
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
- Event Types → — full payload shape per event
- Verify Signature → — implementations in 6 languages
- Retries & Replays → — backoff schedule + manual replay
- Best Practices → — idempotency, dedup, security