Webhooks

Receive real-time HTTP POST notifications when code changes and sync lifecycle events. Subscribe to push and repo sync events, verify HMAC signatures for security, and integrate Code Storage into your CI/CD pipelines, monitoring systems, and product workflows.

Code Storage provides a webhook system that allows you to receive real-time notifications about Git events across your storage layer. This enables you to integrate Code Storage deeply within your product, CI/CD pipelines, monitoring systems, and more.

How webhooks work

Webhooks are HTTP POST requests sent to your specified endpoint whenever certain events occur in your repositories. When you create a webhook subscription, Code Storage will:

1. Monitor Events: Watch for the events you’ve subscribed to (e.g., push or repo.sync.* events)
2. Generate Payloads: Create JSON payloads containing event details
3. Sign Requests: Add cryptographic signatures for security verification
4. Deliver Webhooks: Send HTTP POST requests to your endpoint with automatic retries

Webhook headers

Every webhook request includes the following headers:

• Content-Type: application/json
• User-Agent: Pierre-Webhook/1.0
• X-Pierre-Event: <event_type> (e.g., push, repo.sync.started, repo.sync.succeeded, repo.sync.failed)
• X-Pierre-Signature: t=1642678200,sha256=abc123... (security signature)

Event types

push

Triggered when commits are pushed to a repository.

{
  "repository": {
    "id": "repo_01HZXE4K6YZ1Q2ABCD3EFG45H6",
    "url": "team/project-alpha"
  },
  "ref": "refs/heads/main",
  "before": "abc123def456...",
  "after": "def456abc123...",
  "customer_id": "your-customer-id",
  "pushed_at": "2024-01-20T10:30:00Z"
}

repo.sync.started

Triggered when a repository sync run begins, before the upstream fetch executes. Useful for tracking sync progress or updating status indicators in your UI.

{
  "type": "repo.sync.started",
  "repository": {
    "id": "repo_01HZXE4K6YZ1Q2ABCD3EFG45H6",
    "url": "team/project-alpha"
  },
  "run_count": 1,
  "is_first_sync": true,
  "started_at": "2026-03-17T10:00:00Z"
}

repo.sync.succeeded

Triggered when a sync run completes successfully.

{
  "type": "repo.sync.succeeded",
  "repository": {
    "id": "repo_01HZXE4K6YZ1Q2ABCD3EFG45H6",
    "url": "team/project-alpha"
  },
  "run_count": 1,
  "is_first_sync": true,
  "started_at": "2026-03-17T10:00:00Z",
  "completed_at": "2026-03-17T10:02:30Z"
}

repo.sync.failed

Triggered when a sync run fails, including mirror activity failures (after retries are exhausted) and infrastructure-level failures.

{
  "type": "repo.sync.failed",
  "repository": {
    "id": "repo_01HZXE4K6YZ1Q2ABCD3EFG45H6",
    "url": "team/project-alpha"
  },
  "run_count": 1,
  "is_first_sync": true,
  "started_at": "2026-03-17T10:00:00Z",
  "completed_at": "2026-03-17T10:02:30Z",
  "error": "authentication failed"
}

Sync event fields

Field	Description
run_count	For started, the number of previously completed runs. For succeeded/failed, includes the run that just finished.
is_first_sync	true if the repository had never successfully synced before this run began. Useful for detecting initial sync completion without comparing run counts.
error	Present only on failed events. Possible values: "authentication failed", "failed to clone repository", "failed to push to storage", "repository configuration error", "upstream repository unreachable", "internal error", "session unavailable", "sync failed".

Cancellations triggered internally (e.g., when a repository is detached from its upstream) do not produce a repo.sync.failed event.

Securing webhooks

To ensure the webhooks you receive are legitimate and from Code Storage, you must verify the HMAC signature included with each webhook delivery.

HMAC Signature Verification

Each webhook includes an X-Pierre-Signature header with the format:

X-Pierre-Signature: t=<unix_timestamp>,sha256=<hex_signature>

The signature is computed as:

HMAC-SHA256(webhook_secret, timestamp + "." + payload)

Webhook SDK methods

The SDK provides helper methods to help you validate webhook events quickly.

TypeScript

import { validateWebhook } from '@pierre/storage';

async function handleWebhookRequest(request) {
  // Get the raw request body as text
  const payload = await request.text();

  // Validate the webhook using the SDK
  const result = await validateWebhook(
    payload,
    request.headers, // Headers object with x-pierre-signature and x-pierre-event
    process.env.WEBHOOK_SECRET,
  );

  if (!result.valid) {
    console.error('Invalid webhook:', result.error);
    return new Response('Invalid webhook', { status: 401 });
  }

  // Route by event type
  switch (result.eventType) {
    case 'push':
      console.log(`Push to ${result.payload.ref}`);
      console.log(`Commit: ${result.payload.before} -> ${result.payload.after}`);
      break;
    case 'repo.sync.started':
    case 'repo.sync.succeeded':
    case 'repo.sync.failed': {
      // Sync events are delivered as raw JSON — parse the validated payload
      const sync = JSON.parse(payload);
      console.log(`${result.eventType} for ${sync.repository.id}`);
      if (sync.error) {
        console.log(`Error: ${sync.error}`);
      }
      break;
    }
  }

  return new Response('OK', { status: 200 });
}

Advanced SDK usage

Custom Validation Options:

TypeScript

import { validateWebhook } from '@pierre/storage';

const result = await validateWebhook(payload, headers, webhookSecret, {
  maxAgeSeconds: 600, // Allow webhooks up to 10 minutes old (default: 300)
  // maxAgeSeconds: 0  // Disable timestamp validation entirely
});

Signature-Only Validation for cases where you need more control over the validation process:

TypeScript

import { validateWebhookSignature, parseSignatureHeader } from '@pierre/storage';

// Just validate the signature without parsing the payload
const result = await validateWebhookSignature(
  payload,
  headers['x-pierre-signature'],
  webhookSecret,
);

if (result.valid) {
  // Manually parse and process the payload as needed
  const eventType = headers['x-pierre-event'];
  const webhookData = JSON.parse(payload);
  // ... custom processing logic
}

Common verification errors

When using the SDK, these errors are automatically detected and returned in the result.error field:

• Missing signature components: “Invalid signature header format”
• Timestamp too old: “Webhook timestamp too old (X seconds)”
• Future timestamp: “Webhook timestamp is in the future”
• Signature mismatch: “Invalid signature”
• Invalid JSON: “Invalid JSON payload” (when using validateWebhook)
• Missing headers: “Missing or invalid X-Pierre-Signature header”

Error Handling Best Practices:

TypeScript

import { validateWebhook } from '@pierre/storage';

const result = await validateWebhook(payload, headers, secret);

if (!result.valid) {
  // Log the error for debugging (don't expose to clients)
  console.error('Webhook validation failed:', result.error, {
    timestamp: result.timestamp,
    eventType: result.eventType,
    // Don't log payload or secret for security
  });

  // Return appropriate HTTP status codes
  if (result.error?.includes('timestamp')) {
    return new Response('Request too old', { status: 408 }); // Request Timeout
  }

  return new Response('Invalid webhook signature', { status: 401 });
}