Skip to content
PayloadPuffin.
Join the waitlist

Configure a destination

To receive events at your service, register its HTTPS URL as a destination. You can create one in the console or with POST /v1/destinations. Either way you get a signing secret, which your receiver uses to check that a request came from PayloadPuffin.

Before you start

You need:

  • A receiver that answers POST requests with a 2xx status. Use an HTTPS URL that PayloadPuffin can reach from the internet.
  • For the console, the owner or admin role in your organization.
  • For the API, a key with the destinations:write scope in PAYLOADPUFFIN_API_KEY.

Create it in the console

  1. Switch to the app that should send to this destination.
  2. Open Destinations in the sidebar and click Create destination.
  3. Enter a name, such as Staging receiver, and the URL of your receiver.
  4. Click Create destination.

The console then shows the signing secret, starting with whsec_. Click Copy to clipboard and add the secret to your receiver's configuration.

Create it with the API

Send the destination's name and url:

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"}'
POST/v1/destinationsBodyFull reference
  • name string Required

    Human-readable label for the destination.

    1 to 120 characters

  • url string (uri) Required

    HTTPS URL that receives webhook requests.

  • eventTypes string[] Optional

    Event types this destination receives, matched exactly. Empty receives every type; otherwise the event type must be one of them. Stored sorted, without duplicates.

    At most 100 items

  • channels string[] Optional

    Channels this destination receives. Empty receives every event, with or without channels. Otherwise the event must name at least one of them, so an event that names no channel never reaches it. Stored sorted, without duplicates.

    At most 100 items

  • transformId string Optional

    A destination transform to run on every attempt. Omitted: none.

PayloadPuffin answers 201 Created with the new destination. Keep the id, which starts with dst_, to manage the destination later. signingSecret is the secret to give your receiver:

POST/v1/destinationsReturnsFull reference

201

The command completed.

  • data object Required

    One destination with its recent delivery history.

    • id string Required

      A destination ID, starting with dst_.

    • name string Required

      Human-readable label for the destination.

    • kind string Required

      Transport. Currently only “webhook”.

    • url string (uri) Required

      Where the request is sent.

    • eventTypes string[] Required

      Event types this destination receives, matched exactly. Empty receives every type; otherwise the event type must be one of them. Stored sorted, without duplicates.

      At most 100 items

    • channels string[] Required

      Channels this destination receives. Empty receives every event, with or without channels. Otherwise the event must name at least one of them, so an event that names no channel never reaches it. Stored sorted, without duplicates.

      At most 100 items

    • transformId string | null Required

      The transform every attempt runs before it is signed. Null: payloads are sent as received.

    • enabled boolean Required

      A disabled destination receives no new deliveries; deliveries already created still run. The only way to receive nothing.

    • keepTrying boolean Required

      True keeps trying this destination however many attempts fail; it is never paused automatically.

    • retryPayloadRejections boolean Required

      True retries a delivery answered with 400, 413 or 422 on the normal schedule. False fails it on that attempt.

    • autoPause object | null Required

      Set while the destination is paused for failing: new events still wait for it, nothing is attempted, and resuming sends them. Null otherwise.

    • signingSecretLast4 string Required

      The last four characters of the signing secret, for recognizing it in a masked display.

    • health string Required

      One label for whether this destination needs attention. suspended: the circuit is open or probing, or it is paused for failing. unused: nothing was ever accepted. failing: a failure is counted since the last success, or the 24h success rate is below 50%. idle: deliveries exist but none settled in 24h. healthy otherwise.

      Allowed values: "healthy", "failing", "idle", "unused", "suspended"

    • successRate24h number | null Required

      Percentage of deliveries settled in the last 24 hours that were delivered: delivered24h / (delivered24h + failed24h). A retried attempt is neither. Null when nothing settled, so an unused destination is not reported as zero.

    • attempts24h number Required

      Completed delivery attempts in the last 24 hours, retries included: the traffic figure.

    • delivered24h number Required

      Deliveries settled as delivered in the last 24 hours.

    • failed24h number Required

      Deliveries settled as failed in the last 24 hours after an attempt. A delivery that failed inside PayloadPuffin without reaching the destination doesn’t count here.

    • lastDeliveryAt string | null Required

      Acceptance time of the most recent delivery to this destination. Null when there is none.

    • timeoutMs number Required

      Per-attempt timeout. The request is aborted once it elapses.

    • maxConcurrency number Required

      How many attempts to this destination can run at once. Five unless you set it.

    • rateLimitPerSecond number Required

      The most requests per second this destination is sent. Your plan’s delivery rate unless you set it.

    • rateLimitBurst number Required

      How many requests can go out together before the rate applies. The rate unless you set it; one spaces requests evenly.

    • usesDefaultDeliveryPolicy boolean Required

      True when concurrency, rate limit and burst all follow the defaults, so a change to a default applies here.

    • storeRequests boolean Required

      Whether the request sent on each delivery attempt is stored. Defaults to true.

    • storeResponses boolean Required

      Whether the destination’s response to each delivery attempt is stored. Defaults to true.

    • cooldownUntil string | null Required

      Until when nothing is sent, because the destination answered with Retry-After. Null when it isn’t cooling down.

    • circuitState string Required

      closed: deliveries go out. open: the destination failed repeatedly, and nothing is sent until circuitOpenUntil. half_open: one attempt is testing whether it recovered.

      Allowed values: "closed", "open", "half_open"

    • circuitFailureCount number Required

      Failed attempts in a row since the last success.

    • circuitOpenUntil string | null Required

      When the circuit lets one test attempt through. Null while it is closed.

    • hasPreviousSigningSecret boolean Required

      True while the previous signing secret is still accepted, so a rotated secret can be rolled out gradually.

    • previousSigningSecretExpiresAt string | null Required

      When the previous signing secret stops signing. Null unless it is still active; a rotation is refused until then.

    • previousSigningSecretLast4 string | null Required

      The last four characters of the previous signing secret, for recognizing it. Null together with previousSigningSecretExpiresAt.

    • createdAt string (date-time) Required

      ISO 8601 timestamp.

    • p50AttemptLatencyMs number | null Required

      Median HTTP attempt latency in the last 24 hours. Null when nothing was attempted.

    • p95AttemptLatencyMs number | null Required

      95th percentile HTTP attempt latency in the last 24 hours, as a histogram bucket upper bound. Null when nothing was attempted.

    • lastFailureAt string | null Required

      Time of the latest failed delivery attempt. Null when none failed.

    • lastFailureEventId string | null Required

      The event whose delivery had the latest failed attempt.

    • lastFailureError string | null Required

      Failure reason from the latest failed delivery attempt.

    • recentDeliveries object[] Required

      The five newest deliveries for this destination.

      Show child attributesHide child attributes
      • id string Required

        A delivery ID, starting with dlv_.

      • eventId string Required

        An event ID, starting with evt_.

      • eventType string Required

        The type of the event this delivery carries.

      • status string Required

        “held”: the event arrived too late to deliver, and the delivery waits for you to resend it. “pending”: not attempted yet.

        Allowed values: "pending", "held", "delivering", "retrying", "delivered", "failed"

      • attemptCount number Required

        Attempts recorded so far.

      • acceptedAt string (date-time) Required

        ISO 8601 timestamp.

      • completedAt string | null Required

        When the delivery settled. Null while it is still live.

      • statusCode number | null Required

        HTTP status of the latest attempt. Null when no attempt got a response.

    • signingSecret string | null Required

      The full signing secret. Returned by Create a destination and Rotate a destination signing secret, and by Get a destination with include=secret. Null otherwise.

    • previousSigningSecret string | null Required

      The full previous signing secret, while it is still active. Returned by Get a destination with include=previous_secret. Null otherwise.

The signing secret and your API key do different jobs. Your application sends the API key to PayloadPuffin. Your receiver uses the signing secret to verify what PayloadPuffin sends to it. Verify signatures explains the check.

Find the secret again

Unlike an API key, a signing secret can be shown again. In the console, select the destination and click the reveal button in its Signing secret section. With the API, call Get a destination with include=secret. Revealing a secret needs both destinations:read and destinations:write. Reading a destination without the secret needs only destinations:read.

What the destination receives

You created the destination without eventTypes or channels, so both filters are empty and match everything. The destination receives every event the app accepts, with or without channels. You don't need to set up anything else for your first event.

To limit the destination to certain event types or channels later, see Destinations.

Next steps

Send your first event to the destination.