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:writeandevents:readscopes, stored on your server inPAYLOADPUFFIN_API_KEY. Use the full secret shown when the key was created; theapk_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:
{
"type": "customer.created",
"payload": {
"id": "cus_1042",
"email": "ada@example.com",
"plan": "pro"
}
}These are the body fields POST /v1/events accepts:
/v1/eventsBodyFull referencetypestring RequiredAn 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
payloadunknown RequiredThe 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.
channelsstring[] OptionalChannels 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:
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.jsonThe 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.
/v1/eventsHeadersFull referenceIdempotency-Keystring OptionalApp-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:
/v1/eventsReturnsFull referenceThe event was accepted.202
dataobject RequiredReceipt for an accepted event.
eventIdstring RequiredThe event ID, starting with evt_.
typestring RequiredThe accepted event type.
At least 1 characters
receivedAtstring (date-time) RequiredWhen PayloadPuffin accepted the event.
bytesnumber RequiredSize 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:
export EVENT_ID='evt_...'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 browserThis 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
}