Skip to main content

​
Endpoint

POST https://app.periscope.sh/api/webhooks/deployments

​
Headers

HeaderRequiredValue
AuthorizationYesBearer YOUR_API_KEY
Content-TypeYesapplication/json

​
Request body

{
  "deploymentId": "gha-12345",
  "commitSha": "a1b2c3d4e5f60ab2c3d4e5f60ab2c3d4e5f60ab2",
  "environment": "production",
  "status": "success",
  "startedAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z",
  "service": "api-gateway",
  "branch": "main",
  "triggeredBy": "[email protected]",
  "pipelineName": "Production Deploy",
  "pipelineUrl": "https://github.com/org/repo/actions/runs/12345"
}
See the payload schema for the full field reference.

​
Response

​
Success — new deployment (201)

{
  "action": "created",
  "deploymentId": 42,
  "linkedPRs": 3
}

​
Success — updated existing (200)

When a deployment with the same deploymentId already exists: 
{
  "action": "updated",
  "deploymentId": 42,
  "linkedPRs": 3
}

​
Validation error (400)

{
  "error": "Invalid payload: commitSha must be a valid hex string (5-40 characters)"
}

​
Authentication error (401)

{
  "error": "Invalid or missing API key"
}

​
Organization mismatch (403)

When organizationSlug in the payload does not match the key’s organization: 
{
  "error": "Organization slug does not match API key"
}

​
Behavior

​
Idempotency

The deploymentId field is the idempotency key. Sending the same deploymentId twice updates the existing record rather than creating a duplicate. This is safe for retries.

​
PR linking

On successful production deployments, Periscope automatically:
  1. Matches the commitSha to merged PRs in the database
  2. If previousCommitSha is provided, links all PRs merged between those two commits
  3. Calculates lead_time_seconds for each linked PR

​
Trial activation

If your organization is on the Free plan, the first deployment event triggers a 14-day Business trial.

​
Example

curl -X POST https://app.periscope.sh/api/webhooks/deployments \
  -H "Authorization: Bearer psk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "deploy-001",
    "commitSha": "abc123def456abc123def456abc123def456abc1",
    "environment": "production",
    "status": "success",
    "startedAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:35:00Z",
    "service": "my-api"
  }'