Skip to content
PayloadPuffin.
Join the waitlist

In this quickstart you send one customer.created event from the command line and watch PayloadPuffin deliver it to a webhook receiver. Each step links to the guide that covers it in full. If another service sends the webhooks instead, start with Receive webhooks.

You need a PayloadPuffin console account, curl, and a receiver URL that answers POST requests with a 2xx status. Any HTTPS URL you control works, as long as PayloadPuffin can reach it from the internet.

Pick an app

Sign in to the console. On your first visit, it asks you to create an organization and then your first app. Name the app after an environment, such as staging. Everything below belongs to that app only.

If you already have apps, choose one in the app switcher at the top of the sidebar. You need the owner or admin role to create keys and destinations. Organization explains the roles.

Create an API key

Open API Keys and click Create API key. Give it a name, keep the default expiration, and set Events and Destinations to Write. Click Create key and copy the key from the dialog. It's shown only this once.

Export it so the commands below can use it:

Shell
export PAYLOADPUFFIN_API_KEY='ppk_live_...'

Create an API key covers expiry and scopes.

Add a destination

Create a destination for your receiver. Replace the example URL with yours:

create-destination.sh
curl -X POST "https://api.payloadpuffin.com/v1/destinations" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name": "Staging receiver", "url": "https://example.com/webhooks"}'

curl prints the new destination in data. Its id starts with dst_, and its signingSecret starts with whsec_. The destination now receives every event you send without channels. Configure a destination shows the console flow and what to do with the secret.

Send an event

Save this body as send-event.json:

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

Then send it from the same directory:

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

PayloadPuffin answers 202 Accepted, and curl prints the receipt, with eventId, type, receivedAt and bytes. Copy the eventId. The receipt means PayloadPuffin stored the event, not that your receiver has it yet. Send your first event explains the receipt and the Idempotency-Key header.

See the delivery

Check your receiver first. It should have a POST request whose body is the payload you sent, with webhook-id, webhook-timestamp and webhook-signature headers.

Then ask PayloadPuffin what happened:

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, follow Accepted, but the event isn't visible to check the ID, app and retention.

In the response, data.deliveries has one delivery for your destination. Its status is delivered. Get a delivery lists its attempts, with the statusCode your receiver returned.

In the console, the same event appears on the Events page. Select it to see its deliveries and attempts.

If the status is retrying instead, get the delivery and read its latest attempt to see what failed. PayloadPuffin will try again. Webhook didn't arrive covers retries and other reasons a request hasn't arrived.

Next steps