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

# Payload schema

> Complete field-by-field reference for the deployment webhook payload.

## Required fields

<ResponseField name="deploymentId" type="string" required>
  Unique identifier for this deployment from your CI/CD system. Used as the idempotency key — sending the same `deploymentId` twice updates the existing record.

  Examples: `"gha-12345"`, `"azure-devops-run-67890"`, `"jenkins-build-99999"`
</ResponseField>

<ResponseField name="commitSha" type="string" required>
  The git commit SHA that was deployed. This is the **key field for DORA metrics** — it links the deployment to merged pull requests for lead time calculation.

  Must be 5-40 hexadecimal characters. Use the full 40-character SHA when possible.
</ResponseField>

<ResponseField name="environment" type="string" required>
  The target environment. Standard values:

  * `"production"` — used for DORA metric calculations
  * `"staging"`
  * `"development"`
  * `"preview"`
  * `"test"`

  Custom values are accepted. Only `"production"` deployments contribute to DORA metrics.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current deployment status. Must be one of:

  * `"pending"` — deployment queued or waiting
  * `"in_progress"` — currently deploying
  * `"success"` — deployed successfully
  * `"failure"` — deployment failed
  * `"cancelled"` — deployment was cancelled
  * `"rolled_back"` — deployment was rolled back
</ResponseField>

<ResponseField name="startedAt" type="string" required>
  ISO 8601 timestamp of when the deployment started.

  Example: `"2024-01-15T10:30:00Z"`
</ResponseField>

## Optional fields

<ResponseField name="completedAt" type="string">
  ISO 8601 timestamp of when the deployment completed. **Required** when status is a terminal state: `"success"`, `"failure"`, `"cancelled"`, or `"rolled_back"`.

  Used to calculate deployment duration and MTTR.
</ResponseField>

<ResponseField name="organizationSlug" type="string">
  Your organization slug. Optional — the organization is resolved from the API key. If provided, Periscope validates that it matches the key's organization as a safety check.
</ResponseField>

<ResponseField name="service" type="string">
  Name of the service being deployed. Periscope uses this to:

  * Match the deployment to a repository in your system
  * Group metrics by service (deployment frequency, failure rate)
  * Pair failures with recoveries for MTTR calculation

  Can be the repository name, full name (`org/repo`), or a custom service name.
</ResponseField>

<ResponseField name="branch" type="string">
  The branch that was deployed. Informational — stored for reference but not used in metric calculations.
</ResponseField>

<ResponseField name="previousCommitSha" type="string">
  The commit SHA that was previously deployed to this environment. When provided, Periscope links **all PRs merged between `previousCommitSha` and `commitSha`** to this deployment, enabling accurate lead time for batch deployments.
</ResponseField>

<ResponseField name="triggeredBy" type="string">
  Who or what triggered the deployment. Can be a username, email address, `"automation"`, `"schedule"`, or any custom string.
</ResponseField>

<ResponseField name="pipelineName" type="string">
  Name of the CI/CD pipeline or workflow that performed the deployment. Displayed in the dashboard for context.
</ResponseField>

<ResponseField name="pipelineUrl" type="string">
  URL to view this deployment in your CI/CD system. Displayed as a clickable link in the Periscope dashboard so team members can quickly navigate to the source system.
</ResponseField>

<ResponseField name="rawPayload" type="object">
  The original raw payload from your CI/CD system. If provided, Periscope stores it as-is for future reference. Accepts any JSON object.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom key-value pairs for any additional data you want to track. Values must be `string`, `number`, or `boolean`.

  Common uses:

  * `"version": "2.1.0"` — application version
  * `"releaseNotes": "Bug fixes"` — release description
  * `"featureFlags": "new-checkout-enabled"` — active feature flags
  * `"rollbackInitiated": true` — whether a rollback was triggered
</ResponseField>

## Validation rules

| Rule              | Details                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------- |
| Required fields   | `deploymentId`, `commitSha`, `environment`, `status`, `startedAt` must be non-empty strings  |
| Commit SHA format | 5-40 hexadecimal characters (regex: `/^[a-f0-9]{5,40}$/i`)                                   |
| Status values     | Must be one of the 6 defined statuses                                                        |
| Date format       | `startedAt` and `completedAt` must be valid ISO 8601 dates                                   |
| Terminal status   | `completedAt` is required when status is `success`, `failure`, `cancelled`, or `rolled_back` |