Skip to main content
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 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

​
Example

Here’s an example webhook payload for push events: 
{
  "repository": {
    "id": "team/project-alpha",
    "url": "https://git.code.storage/team/project-alpha"
  },
  "ref": "refs/heads/main",
  "before": "abc123def456...",
  "after": "def456abc123...",
  "customer_id": "your-customer-id",
  "pushed_at": "2024-01-20T10:30:00Z"
}

​
Webhook headers

  • Content-Type: application/json
  • User-Agent: Pierre-Webhook/1.0
  • X-Pierre-Event: push (event type)
  • X-Pierre-Signature: t=1642678200,sha256=abc123... (security signature)

​
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. 
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 });
  }

  // Access validated webhook data
  console.log('Event type:', result.eventType); // e.g., 'push'
  console.log('Repository:', result.payload.repository.id);
  console.log('Pushed at:', result.payload.pushed_at);

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

​
Advanced SDK usage

Custom Validation Options: 
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: 
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: 
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 });
}