Webhooks

Webhook endpoints allow you to receive real-time notifications when events occur in your oCore organization. oCore sends HTTP POST requests to your configured URLs with event details, enabling integrations with external systems, monitoring tools, chat applications, and custom automation.

Creating a Webhook Endpoint

curl -X POST https://ocore.example.com/api/webhook-endpoints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/ocore",
    "events": ["deployment.completed", "deployment.failed", "backup.failed"],
    "secret": "your-webhook-secret-here",
    "description": "Slack notification integration"
  }'

ocore webhook create \
  --url "https://hooks.example.com/ocore" \
  --events deployment.completed,deployment.failed \
  --secret your-webhook-secret-here

Supported Events

Deployment Events

Instance Events

Server Events

Backup Events

Team Events

Wildcard

Subscribe to all events with * (not recommended for production -- use specific events).

Webhook Payload Format

Each webhook delivery sends a JSON payload:

{
  "id": "evt_abc123",
  "type": "deployment.completed",
  "timestamp": "2026-02-26T18:30:00Z",
  "organizationId": "ORG_UUID",
  "data": {
    "deploymentId": "DEPLOYMENT_UUID",
    "projectId": "PROJECT_UUID",
    "branch": "main",
    "commitSha": "abc123def456",
    "status": "completed",
    "durationMs": 45000
  }
}

Payload Fields

HTTP Headers

Webhook Security

Signature Verification

Every webhook delivery includes an X-OCore-Signature header containing an HMAC-SHA256 signature. Verify this signature to ensure the request came from oCore and was not tampered with.

import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require('crypto');

function verifySignature(payloadBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

Best Practices

• Use HTTPS endpoints only (plain HTTP is rejected)
• Store the webhook secret securely (environment variable, not in code)
• Use the event id for idempotency -- the same event may be delivered multiple times
• Respond with HTTP 2xx within 10 seconds -- long processing should be done asynchronously
• Rotate webhook secrets periodically

Managing Webhook Endpoints

Listing Endpoints

curl https://ocore.example.com/api/webhook-endpoints \
  -H "Authorization: Bearer $TOKEN"

Updating an Endpoint

curl -X PUT https://ocore.example.com/api/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["deployment.completed", "deployment.failed", "instance.error"],
    "url": "https://hooks.example.com/ocore-v2"
  }'

Deleting an Endpoint

curl -X DELETE https://ocore.example.com/api/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer $TOKEN"

Viewing Delivery History

Check recent deliveries for an endpoint to debug issues:

curl https://ocore.example.com/api/webhook-endpoints/{endpointId}/deliveries \
  -H "Authorization: Bearer $TOKEN"

Each delivery entry shows:

• Event type and ID
• HTTP status code returned by your endpoint
• Response time
• Request and response bodies (for debugging)
• Retry count

Troubleshooting Webhook Delivery

Endpoint not receiving events

1. Verify the endpoint URL is correct and accessible from the internet
2. Check that your server allows incoming HTTPS connections
3. Verify the events are correctly subscribed
4. Check the delivery history for error details

Deliveries returning 4xx/5xx errors

• 400 Bad Request -- Your endpoint is rejecting the payload. Check your parsing logic
• 401/403 -- Your endpoint requires authentication. Add webhook-specific auth handling
• 500 -- Your endpoint is crashing. Check server logs
• Timeout -- Your endpoint takes too long. Process asynchronously and return 200 immediately

Duplicate deliveries

• oCore retries failed deliveries (up to 3 times with exponential backoff)
• Use the id field for idempotency to prevent duplicate processing
• Return HTTP 2xx on the first attempt to prevent retries

Signature verification failing

• Ensure you are using the raw request body (not parsed JSON) for HMAC computation
• Verify the secret matches exactly (no trailing whitespace)
• Check that you are using HMAC-SHA256 (not SHA-1 or SHA-512)
• Ensure the comparison is timing-safe to prevent timing attacks

Events not matching expected types

• Review the supported events list above
• Event types are case-sensitive
• Use the * wildcard during development to see all events, then narrow down

Required Permissions

Troubleshooting

Webhook delivery consistently failing

• Check that your endpoint responds within 10 seconds
• Ensure your HTTPS certificate is valid (self-signed certificates may be rejected)
• Verify there are no firewalls blocking incoming connections
• Test the endpoint manually with curl to confirm it accepts POST requests

Too many webhook events

• Subscribe only to the events you need (avoid * in production)
• Implement rate limiting on your endpoint if needed
• Use a message queue on your end for buffering high-volume events