Overview

The External Events API lets your systems tell Pushly that something happened: a flight was delayed, a price crossed a threshold, an order shipped, a weather alert was issued. Each event has a name, the subscribers it concerns, and any properties you want to attach to it.

Your marketing team builds journeys in the Pushly platform that listen for an event by name. When an event arrives, every journey listening for it can:

• decide whether this particular event qualifies, using conditions on its properties (for example, only delays over 30 minutes);
• decide who receives it, either the subscribers you named or, for a broadcast event, the journey's own audience rules, including a geographic area carried on the event;
• put the event's values into the notification, for example {{event.properties.gate}} in a title or landing URL.

You send events. The marketer decides what each event does. You do not need to know which journeys exist, and a journey can be changed without any change on your side.

Events are processed asynchronously. A successful response means Pushly has stored the event and queued it for matching. It does not mean a notification has been sent.

Endpoint

POST https://api.pushly.com/domains/{domain_id}/events

domain_id is the ID of the Pushly domain the events belong to. A request carries events for one domain only.

Authentication

The External Events API uses the same API keys as the rest of the Pushly API. Send the key in the X-API-KEY header:

X-API-KEY: {key}

The key must be an API token: either a domain API token for the domain in the path, or an organization API token with access to that domain. Admin users can create tokens in the platform. See Getting Started for where to create one.

A key that is not an API token, or one with no access to the domain in the path, is refused with 403. Nothing in the request is processed.

If request signing has been set up for your domain, every request must also be signed. See Request signing.

Quick start

The request below sends one event to two subscribers identified by your own user IDs.

curl --request POST \
     --url 'https://api.pushly.com/domains/1234/events' \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "events": [
    {
      "event_id": "flight-delay-UA123-2026-10-07",
      "event_name": "flight_delayed",
      "audience": { "external_ids": ["user-81723", "user-11904"] },
      "properties": {
        "flight_number": "UA123",
        "delay_minutes": 45,
        "gate": "B12"
      }
    }
  ]
}'

// Node 18+ (built-in fetch)
const response = await fetch("https://api.pushly.com/domains/1234/events", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.PUSHLY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "flight-delay-UA123-2026-10-07",
        event_name: "flight_delayed",
        audience: { external_ids: ["user-81723", "user-11904"] },
        properties: { flight_number: "UA123", delay_minutes: 45, gate: "B12" },
      },
    ],
  }),
});

const result = await response.json();
for (const [eventId, outcome] of Object.entries(result.data)) {
  if (outcome.error_message) console.error(eventId, outcome.status, outcome.error_message);
  if (outcome.warnings) console.warn(eventId, outcome.warnings);
}

import os
import requests

response = requests.post(
    "https://api.pushly.com/domains/1234/events",
    headers={"X-API-KEY": os.environ["PUSHLY_API_KEY"]},
    json={
        "events": [
            {
                "event_id": "flight-delay-UA123-2026-10-07",
                "event_name": "flight_delayed",
                "audience": {"external_ids": ["user-81723", "user-11904"]},
                "properties": {"flight_number": "UA123", "delay_minutes": 45, "gate": "B12"},
            }
        ]
    },
    timeout=30,
)

for event_id, outcome in response.json()["data"].items():
    if "error_message" in outcome:
        print("rejected", event_id, outcome["status"], outcome["error_message"])
    for warning in outcome.get("warnings", []):
        print("warning", event_id, warning)

A successful response:

{
  "status": "success",
  "data": {
    "flight-delay-UA123-2026-10-07": { "status": 202 }
  }
}

The first time Pushly sees a new event name, the response also carries a warning saying the event type has been queued for registration. That is expected. See Properties and types.

The request

The body is a JSON object with an events array and an optional trace_id.

Event fields

Fields not listed here are ignored.

Timestamps are ISO 8601 strings, such as 2026-10-07T14:30:00Z or 2026-10-07T10:30:00-04:00, or a number of seconds since the Unix epoch. A string with no offset is read as UTC. Include an offset to avoid ambiguity. Milliseconds since the epoch are not supported.

Audiences

Every event must declare exactly one audience. An event that declares none, or more than one, makes the whole request fail with 400. This is deliberate: if a missing field could quietly turn into "everyone", a bug on either side could send a notification meant for one person to your whole audience.

Targeted events

Name the recipients with one kind of identifier:

Each must be an array of non-empty strings. Use one kind per event; to reach subscribers known by different kinds of ID, send separate events.

{
  "event_id": "order-559310-shipped",
  "event_name": "order_shipped",
  "audience": { "external_ids": ["user-81723"] },
  "occurred_at": "2026-10-07T14:02:11Z",
  "properties": {
    "order_id": "559310",
    "carrier": "UPS",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "items": 3,
    "estimated_delivery": "2026-10-09"
  }
}

Identifiers are matched against the domain in the path only. An identifier that names no subscriber on that domain is skipped; the response does not report it. Duplicate identifiers within one event are sent to once.

A targeted event still goes only to subscribers a listening journey allows: the journey's own rules, such as frequency limits, still apply.

Broadcast events

Set broadcast to true to name no one. Each listening journey then uses its own audience rules to decide who receives the event.

Broadcast events suit things that are not about one person, such as a weather alert, a market move or a breaking story. A journey can combine its own rules with values from the event. For example, a journey can target subscribers whose location falls inside a geographic area that the event carries.

{
  "event_id": "nws-alert-KS-2026-10-07T1430Z",
  "event_name": "severe_weather_alert",
  "audience": { "broadcast": true },
  "priority": "high",
  "occurred_at": "2026-10-07T14:30:00Z",
  "expires_at": "2026-10-07T16:00:00Z",
  "properties": {
    "headline": "Severe thunderstorm warning",
    "severity": "severe",
    "area": {
      "points": [
        [-95.0, 39.5],
        [-94.0, 39.5],
        [-94.0, 38.5],
        [-95.0, 38.5],
        [-95.0, 39.5]
      ]
    }
  }
}

Geographic areas

To let a journey target subscribers by location, send the area as an object with a points array of [longitude, latitude] pairs:

{ "points": [[-95.0, 39.5], [-94.0, 39.5], [-94.0, 38.5], [-95.0, 38.5], [-95.0, 39.5]] }

• Longitude comes first, then latitude.
• At least three points are required. Close the ring by repeating the first point at the end.
• GeoJSON objects ({"type": "Polygon", "coordinates": ...}) and bare arrays of points are not accepted for location targeting. An area in the wrong shape is still accepted at ingestion, but journeys that target on it cannot use it.

You can name the property anything (area in the example above). The marketer picks it when building the journey. Areas are stored exactly as sent, so each event that carries one gets a warning that its points property "could not be typed and was kept exactly as sent". That is expected for an area and needs no action.

Idempotency and retries

event_id is how Pushly recognizes an event it has already received. An event is identified by its domain, event_name and event_id together.

• Re-sending an event is safe. If Pushly has already accepted an event with the same name and ID, a re-send does not produce a second notification.
• Keep event_id stable across retries. Generate it once, when the event happens in your system, and store it with the event. Do not generate a new ID per HTTP attempt. A new ID makes a new event.
• The first arrival wins. A re-send cannot change an event that was already accepted. Its properties, its arrival time and its expiry stay as they were the first time. To send corrected data, send a new event with a new event_id.
• The same event_id may be used under different event names; those are different events.

Pushly remembers an event for at least as long as it retains it (30 days by default; see Relevance and expiry).

What to retry

When retrying only the failed events from a partly successful request, send just those events. Re-sending the accepted ones is harmless but unnecessary.

Properties and types

properties is a JSON object of your choosing. Nested objects are allowed, and nested values are addressed with dots: {"flight": {"gate": "B12"}} becomes flight.gate, used in a message as {{event.properties.flight.gate}}.

Automatic registration

You do not need to declare event names or properties before sending them.

• The first event with a new event_name (and schema_version) is accepted and its type is registered automatically. Registration takes a few minutes, and events sent in the meantime each carry a warning that the type "has been queued for registration". They are still accepted.
• Each new property is registered with a type inferred from its first values.
• Before a marketer builds a journey on a new event, send one representative event, with every property filled in, so the event and its properties are available to choose from.

Inferred types:

Some values have no type that can be registered: null, an empty array, an array of mixed types, an array of objects or arrays (such as a geographic area), or objects nested more than five levels deep. These values are kept exactly as sent and can still be used in messages and as a journey's geographic area. They cannot be used in a journey condition of their own, and the response warns that the property "could not be typed".

Once a type is registered

A registered property keeps its type. Later values are converted to it where possible, for example "45" to 45 for an integer property. A value that cannot be converted is dropped from that event, and the event is still accepted with a warning naming the property.

A property registered as a number is never changed to a string. If one batch sends both 45 and "n/a" for a new property, it is registered as a number and "n/a" is dropped, with a warning. Send numbers consistently, and leave a property out rather than sending a placeholder string.

To change a property's type or the overall shape of an event, increase schema_version. Journeys pinned to the old version keep working.

Limits on registration

Pushly can raise the event-type limit for a domain.

Template delimiters are removed

Notification content in Pushly is rendered with Liquid templates. So that event data can never be interpreted as template code, the delimiters {{, }}, {%, %} and -%} are removed from:

• event_name;
• every property key, at any depth;
• every string property value, at any depth, including strings inside arrays.

For example, "Hello {{ name }}" is stored as "Hello name ". No warning is returned. If your data legitimately contains these character pairs, they will not reach the notification.

A key that is empty after removal is dropped.

Relevance and expiry

Some events stop being useful quickly: a gate change is worthless after the flight leaves. Set expires_at to the moment the event should stop producing notifications.

• An event that arrives already expired is accepted with status 202 and a warning saying it expired and was not sent. Its arrival is recorded, but it triggers nothing.
• An event that expires while it is being processed is dropped at that point. Pushly checks expiry again before a notification is built.
• If you leave expires_at out, the event stays relevant for 24 hours after it arrives, unless Pushly has configured a different window for your domain or event type.
• Re-sending an event does not extend its expiry. The expiry from the first arrival applies.

Separately, Pushly retains each event's properties so that later steps of a journey can still use them in messages. Retention is 30 days by default and can be configured up to two years. An event is never relevant for longer than it is retained, so an expires_at beyond the retention period is shortened to it.

Priority

priority asks for faster processing relative to your other events:

Priority is a request. Each event type has a ceiling, high unless Pushly has configured otherwise, and a higher request is lowered to it. A value outside this list fails the whole request with 400. Values are lower-case.

Limits

The properties size is measured on the properties as stored, written as compact JSON in which non-ASCII characters are escaped as \uXXXX (6 bytes each). Text in non-Latin scripts therefore counts for more than its UTF-8 size. Leave headroom.

The response

Every response that reaches the API has the same shape:

{
  "status": "success",
  "data": {
    "<event_id>": {
      "status": 202,
      "error_message": "...",
      "warnings": ["..."]
    }
  }
}

Once the request has been read, the HTTP status is 202 even if no event in it was accepted. Always read the per-event statuses. Treat the presence of error_message as the failure signal.

If two events in one request share an event_id under different event names, the second is keyed event_name/event_id so that neither result replaces the other.

A response with failures and warnings:

{
  "status": "success",
  "data": {
    "evt-1001": { "status": 202 },
    "evt-1002": {
      "status": 202,
      "warnings": [
        "Property 'delay_minutes' kept its numeric type; values that are not numbers were dropped."
      ]
    },
    "evt-1003": {
      "status": 413,
      "error_message": "Event properties are 61440 bytes, over the 51200 byte limit."
    },
    "evt-1004": {
      "status": 500,
      "error_message": "The event could not be stored. It was not queued; send it again."
    }
  }
}

Whole-request errors

When the request is refused before any event is considered, data has a single entry under the reserved key _batch, and the HTTP status matches it:

{
  "status": "error",
  "data": {
    "_batch": {
      "status": 400,
      "error_message": "Event 'flight_delayed' at position 0 carries no event_id. Supply a string that stays the same when the event is sent again."
    }
  }
}

Errors in the envelope reject the whole request: one bad event means none are accepted. Problems with a property value only ever affect that event, and are reported as warnings.

Unexpected server errors return HTTP 500 with a different body, and no per-event results:

{
  "status": "error",
  "error_type": "internal_server_error",
  "status_code": 500,
  "message": "An unexpected error occurred during your request."
}

Retry these as described in What to retry. A request with a missing or invalid API key may be refused before it reaches the API, with a body that has neither shape.

Request signing

Request signing lets Pushly confirm that a request came from you and was not altered in transit. It is optional, and is enforced only for domains where a signing secret has been set up.

🚧

Not yet self-service

Signing secrets are set up by Pushly. Contact your Pushly account manager to enable request signing for a domain. Once a secret is set up, every request for that domain must be signed. Unsigned requests are refused with 401.

To sign a request:

1. Take the current time as a Unix timestamp in seconds.
2. Build the string {timestamp}.{body}, where body is the exact bytes you are sending as the request body.
3. Compute an HMAC-SHA256 of that string using your signing secret as the key, and hex-encode it in lower case.
4. Send it in the X-Pushly-Signature header:

X-Pushly-Signature: t=1791383400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

The timestamp must be within five minutes of Pushly's clock, in either direction, so keep your servers' clocks synchronised. During a secret rotation you may send more than one signature, t=...,v1=<sig1>,v1=<sig2>. The request is accepted if any of them matches.

Sign the body after serializing it, and send exactly those bytes. Serializing again, or letting your HTTP client re-encode the JSON, changes whitespace or key order and the signature will not match.

import { createHmac } from "node:crypto";

const body = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000);
const signature = createHmac("sha256", process.env.PUSHLY_SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest("hex");

await fetch("https://api.pushly.com/domains/1234/events", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.PUSHLY_API_KEY,
    "Content-Type": "application/json",
    "X-Pushly-Signature": `t=${timestamp},v1=${signature}`,
  },
  body,
});

import hashlib
import hmac
import json
import os
import time

import requests

body = json.dumps(payload, separators=(",", ":")).encode()
timestamp = int(time.time())
signature = hmac.new(
    os.environ["PUSHLY_SIGNING_SECRET"].encode(),
    f"{timestamp}.".encode() + body,
    hashlib.sha256,
).hexdigest()

requests.post(
    "https://api.pushly.com/domains/1234/events",
    headers={
        "X-API-KEY": os.environ["PUSHLY_API_KEY"],
        "Content-Type": "application/json",
        "X-Pushly-Signature": f"t={timestamp},v1={signature}",
    },
    data=body,  # send the signed bytes, not json=
    timeout=30,
)

BODY='{"events":[{"event_id":"evt-1","event_name":"flight_delayed","audience":{"broadcast":true}}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$PUSHLY_SIGNING_SECRET" -hex | sed 's/^.* //')

curl --request POST \
     --url 'https://api.pushly.com/domains/1234/events' \
     --header "X-API-KEY: $PUSHLY_API_KEY" \
     --header 'Content-Type: application/json' \
     --header "X-Pushly-Signature: t=$TS,v1=$SIG" \
     --data "$BODY"

Best practices

• Generate event_id from your own data, for example the order number and the state it moved to, so the same real-world event always produces the same ID.
• Batch events. Up to 100 events per request is more efficient than one request per event.
• Read every per-event status. A 202 HTTP response can still contain events that were not accepted.
• Log warnings. They are how you find out that a property was dropped or not registered.
• Set expires_at for anything time-sensitive, so a delayed event cannot produce a stale notification.
• Keep event names and property types stable. Journeys are built on them.