Webhooks

Webhook Signature Verification

Pixop signs all outgoing webhook requests to allow you to verify their authenticity and integrity.

Each request includes the following HTTP headers:

X-Pixop-Signature: A base64-encoded signature of the timestamp and request body.
X-Pixop-Public-Key-Id: The UUID of the public key used to verify the signature.
X-Pixop-Timestamp: A Unix timestamp (in seconds) indicating when the request was signed.
X-Pixop-Algorithm: The signing algorithm. Currently, SHA256withECDSA.

Signature format:

<timestamp>.<payloadJson>

<timestamp> is taken from X-Pixop-Timestamp
<payloadJson> is the raw request body as sent by Pixop

This string is signed using ECDSA (SHA256withECDSA), and the result is base64-encoded.

Verifying the Signature

Concatenate the timestamp and request body:
```
timestamp + "." + rawRequestBody
```
Retrieve the public key using the X-Pixop-Public-Key-Id:

GET /v1/webhooks/public-keys/{id}
Verify the signature using the specified algorithm and public key.
Reject requests with timestamps older than an acceptable threshold (e.g., 5 minutes) to mitigate replay attacks.

⏱ Webhook requests have a 10-second timeout. Respond promptly and handle long-running logic asynchronously to avoid delivery failures.

Although public key retrieval is typically fast, it's strongly recommended to cache it to reduce latency and improve performance.

Key Rotation

Pixop rotates webhook signing keys regularly. During rotation, two keys may be valid for a short grace period. Always verify the signature using the public key referenced by X-Pixop-Public-Key-Id.

Code Example

A public Spring Boot example project will be available to demonstrate webhook signature verification.

Webhook Retry Behavior

Pixop automatically retries failed webhook deliveries using an exponential backoff strategy. Retry behavior can be customized per webhook.

A delivery is considered failed if:

The response status code is not 2xx
The request times out or encounters a network error
The WebhookRateLimitPerSecond threshold is exceeded and no permit is acquired within 5 seconds

If a 429 Too Many Requests response includes a Retry-After header (or similar), Pixop honors it when scheduling the next retry attempt.

Retries continue until the maximum retry duration (maxTotalRetryDelayMinutes) is reached.

Detailed delivery history — including status codes, response bodies, retry timing, and headers — is available via the GET /v1/webhooks/events endpoint.

📅 Webhook event history is retained for 10 days, or 1 day for test events.

Event Ordering and Context

Webhook events are dispatched asynchronously and independently. While Pixop makes a best-effort attempt to deliver events in the order they occur, delivery order is not guaranteed.

For instance, a video_processing.done event may arrive before the corresponding video_processing.started event for the same videoId.

To correctly handle events:

Treat each event as self-contained
Use the occurredAt date and time to determine the actual sequence of events
Design webhook receivers to be idempotent and resilient to out-of-order delivery

For additional context about a given event, query the related video resource using:
GET /v1/videos/{videoId}