Webhooks

API-enabled organizations receive webhooks instead of email when Insta Swaps change state. Manage endpoints in the app (Developer → Webhooks) or via POST /webhooks.

Events

Event	When
`insta_swap.queued`	Job entered the render queue
`insta_swap.completed`	Render finished; result available
`insta_swap.failed`	Render failed
`digital_sample.analysis.completed`	Forensic video analysis finished; variation proposals drafted
`digital_sample.analysis.failed`	Forensic video analysis failed
`webhook.test`	Verification or manual test ping (not stored as a subscription)

Webhook events ≠ Insta Swap status. A swap moves through many pipeline states (QUEUED, ASSIGNED, RENDERING, PENDING_APPROVAL, COMPLETED, FAILED, EXPIRED, CANCELLED) visible on GET /insta-swaps/{id}. Public webhooks only fire at three integration milestones — queued, completed, and failed — so partners are not flooded with intermediate GPU/render updates. Mid-flight progress is for polling, not subscription.

Create an endpoint

curl -s -X POST "$BASE_URL/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/yph",
    "events": ["insta_swap.completed", "insta_swap.failed"],
    "verify": true
  }'

When verify is true (default), YPH sends webhook.test before saving. Your URL must respond with HTTP 2xx. On success, the response includes a signing secret (shown once):

{
  "endpoint": {
    "id": "…",
    "url": "https://example.com/webhooks/yph",
    "events": ["insta_swap.completed", "insta_swap.failed"],
    "secret": "…",
    "enabled": true
  }
}

Payload shape

{
  "event": "insta_swap.completed",
  "idempotencyKey": "insta_swap.completed:job-uuid",
  "createdAt": "2026-06-20T12:00:00.000Z",
  "data": {
    "jobId": "…",
    "digitalSampleId": "…",
    "actorId": "…",
    "status": "COMPLETED"
  }
}

Verify signatures

Each delivery includes:

Header	Value
`X-YPH-Event`	Event name
`X-YPH-Idempotency-Key`	Dedup key
`X-YPH-Signature`	`sha256=<hex>`

Compute the signature:

signature = SHA256( secret + ":" + raw_request_body )

Compare to X-YPH-Signature (strip the sha256= prefix). Use constant-time comparison in production.

Reject requests with invalid signatures. The secret is only returned at endpoint creation.

List and delete

curl -s "$BASE_URL/webhooks" -H "Authorization: Bearer YOUR_API_KEY"
curl -s -X DELETE "$BASE_URL/webhooks/ENDPOINT_ID" -H "Authorization: Bearer YOUR_API_KEY"

Delivery history: GET /webhooks/{id}/deliveries.

Retries

Failed deliveries are retried with exponential backoff (up to 3 attempts). Check last_error in delivery records for debugging.

Get started

Integrations

AI Integrators

Events

Create an endpoint

Payload shape

Verify signatures

List and delete

Retries

​Events

​Create an endpoint

​Payload shape

​Verify signatures

​List and delete

​Retries

Events

Create an endpoint

Payload shape

Verify signatures

List and delete

Retries