Skip to content
PayloadPuffin.
Join the waitlist

Send an event

POST/v1/eventspreview

Send an event to every destination that matches it. Returns 202 once the event is stored, and PayloadPuffin delivers it from there. With an Idempotency-Key, a repeat within the app returns the first receipt; when the key can’t be checked, the request is refused with 503 and nothing is accepted. While an earlier request with the same key is still being accepted, it is refused with 409; retry after Retry-After with the same key.

Headers

  • Idempotency-Key string Optional

    App-scoped idempotency key of 1 to 48 characters (a UUID is 36), retained for 24 hours after acceptance. The first accepted submission wins: reusing the key returns its original receipt, whatever the new request contains. While the first request is still being processed, 409 with Retry-After. If the key store cannot be reached, 503 with Retry-After and nothing is accepted.

    1 to 48 characters

Body

  • type string Required

    An event type, for example customer.created. Matched exactly and case-sensitively. Spaces, commas and other printable characters are allowed; control characters (U+0000 to U+001F, U+007F to U+009F, which include newline, tab and carriage return) and unpaired UTF-16 surrogates are not.

    1 to 64 characters

  • payload unknown Required

    The event body, delivered as the exact bytes you sent: any JSON value. PayloadPuffin never parses or reformats it. A request with more than one payload member is refused with 400. The whole request, this wrapper included, may be at most 262,144 bytes (256 KiB), and the wrapper’s other members at most 65,536 bytes. A payload that isn’t valid JSON but closes every string, object and array is accepted and sent on as is; a transform fails on it, or the receiver rejects it. An API key that keeps sending requests over a size limit gets 429 with Retry-After for a while.

  • channels string[] Optional

    Channels this event is addressed to, by slug. It reaches destinations that list one of them and destinations that list no channel. Omitted or empty: only destinations that list no channel.

    At most 10 items

Returns

202

The event was accepted.

  • data object Required

    Receipt for an accepted event.

    • eventId string Required

      The event ID, starting with evt_.

    • type string Required

      The accepted event type.

      At least 1 characters

    • receivedAt string (date-time) Required

      When PayloadPuffin accepted the event.

    • bytes number Required

      Size of the payload in bytes, as delivered before any transform.

      At least 0

Example

Request
curl -X POST "https://api.payloadpuffin.com/v1/events" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"customer.created","payload":null}'
Response 202
{
  "data": {
    "eventId": "eventId",
    "type": "type",
    "receivedAt": "receivedAt",
    "bytes": 0
  }
}

Errors

Errors use application/problem+json. The code member is stable; branch on it rather than on title or detail.

  • 4XX application/problem+json

    The request was rejected.