Skip to main content
A webhook destination is a project-scoped HTTPS endpoint subscribed to a set of event types at a fixed payload API version. Browse the automatic command reference.

​
Discover versions and events

Payload API versions are calendar dates. Each version has its own event catalog, so list the versions first and then the events for the one you want:

​
Create a destination

Repeat --event for each type you need, or pass --all-events on its own. The CLI sorts explicit events and rejects duplicates.
Names are trimmed and limited to 256 characters. Descriptions are limited to 1,000 characters and are cleared only with --clear-description. URLs are canonicalized and must use HTTPS, fit in 2,048 characters, and carry no credentials or fragment. Photon handles DNS, redirect, and private-network checks at delivery time. Destinations default to enabled.
create returns signingSecret exactly once. Store it before the command scrolls away. The secret is flushed to stdout before the local journal record is acknowledged, so if your terminal dies you can recover it with photon operation replay — it is never written to the journal itself.

​
Edit and disable

Passing --event to edit replaces the complete subscription rather than adding to it.

​
Upgrade the API version

The API version is immutable on an existing destination. Run both in parallel instead:
1

Create a second destination on the new version

Point it at the same or a new endpoint.
2

Accept both payload versions

Your consumer needs to handle both for as long as they run together.
3

Verify the new consumer

Confirm the new version’s events are processed correctly.
4

Delete the old destination

​
Rotate the signing secret

Rotation returns a new secret once and keeps the previous one valid for 86,400 seconds by default:
--overlap-seconds accepts 0 through 604800.
--overlap-seconds 0 invalidates the old secret immediately and will drop deliveries your consumer has not caught up on. Reserve it for emergency rotation after a leak.

​
Verify deliveries

Photon signs deliveries with the Standard Webhooks format. Verify against the raw request body and the webhook-id, webhook-timestamp, and webhook-signature headers before you parse the body. During an overlap window, accept signatures from either configured secret, then drop the old one after previousSecretExpiresAt.

​
JSON envelopes

list, view, edit, delete, errors, --debug output, and the journal never expose a signing secret.
The API does not yet offer delivery history, test delivery, or redelivery, so the CLI has no commands for them.

​
Catalog metadata

Version discovery reports whether a version is selectable, its successor, and retirement guidance, along with the contract namespace and package version. Event types include audience and schemaProfile; schemaUrl is a relative API path. Resolve it against the same Photon API origin.