Skip to content
PayloadPuffin.
Join the waitlist

Send your first event

Your application reports something that happened by sending an event. PayloadPuffin stores it and delivers it to every destination whose filters match.

Before you start

You need:

  • An API key with the events:write and events:read scopes, stored on your server in PAYLOADPUFFIN_API_KEY. Use the full secret shown when the key was created; the apk_ key ID can't authenticate.
  • A destination, so the event has somewhere to go. A destination created without filters receives every event, including events you send without channels.

Write the event

An event is a JSON object with a type you choose and a payload. The payload can be any JSON value; PayloadPuffin delivers its bytes exactly as you send them unless a transform rewrites them.

Save this body as send-event.json:

send-event.json
{
	"type": "customer.created",
	"payload": {
		"id": "cus_1042",
		"email": "ada@example.com",
		"plan": "pro"
	}
}

These are the body fields POST /v1/events accepts:

POST/v1/eventsBodyFull reference
  • 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

Leave out channels for now. Channels send an event to only some of your customers. Without them, the event reaches every destination that lists none, and an empty list means the same.

Send it

From the directory where you saved send-event.json, send it with your API key as a Bearer token:

send-event.sh
curl -X POST "https://api.payloadpuffin.com/v1/events" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-1042-created" \
  --data-binary @send-event.json

The Idempotency-Key header is optional. Reuse the same key when you retry the same event: for 24 hours, the first accepted request with that key wins and every repeat returns its receipt, even if the body has changed.

POST/v1/eventsHeadersFull reference
  • 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

Read the receipt

PayloadPuffin answers 202 Accepted with a receipt:

POST/v1/eventsReturnsFull reference

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

bytes counts the payload alone, not the surrounding JSON. Keep eventId to look the event up later.

What a 202 means

A 202 receipt means PayloadPuffin has stored the event durably and will deliver it. It does not mean any destination has received it yet: delivery happens afterwards, and a newly accepted event may take a moment to appear in event queries.

Acceptance is not delivery success. If no destination matches the event, it is accepted and produces no deliveries. Each delivery is retried on its own, and your receiver may see the same event more than once, so make it safe to process duplicates.

Check the delivery

Look the event up with Get an event. Reading it needs the events:read scope. Set EVENT_ID to the eventId from your receipt:

Shell
export EVENT_ID='evt_...'
get-event.sh
curl "https://api.payloadpuffin.com/v1/events/$EVENT_ID" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY"

A newly accepted event can briefly return 404 while processing finishes. Retry after a few seconds. If it still isn't found, check the receipt's eventId and use a key for the same app. Read events explains when a stored event is available and when retention removes it.

The response lists one delivery in data.deliveries for each matching destination, with its status and attemptCount; Get a delivery lists its attempts. A status of delivered means your destination answered an attempt with a 2xx. While a delivery waits for its next attempt, its status is retrying and nextAttemptAt says when. An event sent through POST /v1/events with an empty deliveries list matched no destination. Webhook didn't arrive helps you follow up.

Try it

Try it: POST /v1/events

Runs in your browser

This playground applies the checks PayloadPuffin makes when it accepts an event, using the same framing code and the published request schema. It sends nothing and stores nothing, so its event IDs are not real. Edit the body, reuse an Idempotency-Key, or break the JSON to see the response you would get. Without JavaScript you see the starting request and the receipt it produces.

202 Accepted

{
  "eventId": "evt_01m5yc50qxe0ctzkfv78c2n647",
  "type": "customer.created",
  "receivedAt": "2026-10-27T09:48:04.733Z",
  "bytes": 70
}