> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Webhooks

> Subscribe HTTPS endpoints to project events and manage signing secrets.

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](/docs/beta/cli/reference/index).

## 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:

```sh theme={null}
photon project webhook api-version list
photon project webhook event-type list --api-version 2026-07-01
```

## 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.

```sh theme={null}
photon project webhook create \
  --name production-messages \
  --url https://hooks.example.com/photon \
  --api-version 2026-07-01 \
  --event message.created \
  --event message.updated
```

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`.

<Warning>
  `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`](/docs/beta/cli/operations#replay) — it is never written to
  the journal itself.
</Warning>

## Edit and disable

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

```sh theme={null}
photon project webhook edit pho_whd_... --status disabled
photon project webhook list --limit 100
photon project webhook delete pho_whd_... --force
```

## Upgrade the API version

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

<Steps>
  <Step title="Create a second destination on the new version">
    Point it at the same or a new endpoint.
  </Step>

  <Step title="Accept both payload versions">
    Your consumer needs to handle both for as long as they run together.
  </Step>

  <Step title="Verify the new consumer">
    Confirm the new version's events are processed correctly.
  </Step>

  <Step title="Delete the old destination">
    ```sh theme={null}
    photon project webhook delete pho_whd_old... --force
    ```
  </Step>
</Steps>

## Rotate the signing secret

Rotation returns a new secret once and keeps the previous one valid for 86,400
seconds by default:

```sh theme={null}
photon project webhook rotate-secret pho_whd_... \
  --overlap-seconds 86400 \
  --force
```

`--overlap-seconds` accepts `0` through `604800`.

<Warning>
  `--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.
</Warning>

## Verify deliveries

Photon signs deliveries with the
[Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)
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

| Command | Envelope |
| - | - |
| `list` | `{"destinations": [...], "nextPageToken": "..."}` |
| `view`, `edit` | `{"destination": ...}` |
| `create` | `{"destination": ..., "signingSecret": "..."}` |
| `rotate-secret` | `destinationId`, `previousSecretExpiresAt`, `signingSecret` |
| `api-version list` | `{"apiVersions": [...]}` |

`list`, `view`, `edit`, `delete`, errors, `--debug` output, and the journal
never expose a signing secret.

<Note>
  The API does not yet offer delivery history, test delivery, or redelivery, so
  the CLI has no commands for them.
</Note>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.