Webhooks

Outgoing webhooks let you receive real-time HTTP notifications when events happen in your oec.sh environments — deployments complete, environments are created, statuses change. Instead of polling, your server receives a push.

Base URL: https://api.oec.sh/api/public/v1

Available Events

Deployment Events

Environment Events

Automation Rule Events

You can subscribe to up to 10 events per webhook.

Setup

List Webhooks

GET /webhooks

Returns all webhooks for your organisation (or project, if using a project-scoped key).

Query Parameters

Response — 200 OK

{
  "items": [
    {
      "id": "wh-uuid",
      "url": "https://hooks.example.com/oec-events",
      "events": ["deploy.completed", "deploy.failed"],
      "description": "CI/CD notifications",
      "project_id": null,
      "is_active": true,
      "last_triggered_at": "2026-03-01T14:22:00Z",
      "failure_count": 0,
      "created_at": "2026-01-15T09:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Create Webhook

POST /webhooks

Registers a new outgoing webhook. Requires a full_access API key.

Limits

• Max 100 webhooks per organisation
• Webhook mutation rate limit: 10 create/update/delete per minute per API key

Request Body

Response — 201 Created

{
  "id": "wh-uuid",
  "url": "https://hooks.example.com/oec-events",
  "events": ["deploy.completed", "deploy.failed"],
  "description": "CI/CD notifications",
  "project_id": null,
  "is_active": true,
  "last_triggered_at": null,
  "failure_count": 0,
  "created_at": "2026-03-13T10:00:00Z",
  "secret": "whsec_abc123..."
}

Example

curl -X POST "https://api.oec.sh/api/public/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://hooks.example.com/oec-events",
    "events": ["deploy.completed", "deploy.failed", "environment.created"],
    "description": "CI/CD pipeline notifications"
  }'

Get Webhook

GET /webhooks/{webhook_id}

Returns a single webhook by ID.

Update Webhook

PATCH /webhooks/{webhook_id}

Updates a webhook's URL, events, description, or active state. Requires full_access key. All fields are optional.

Request Body

Example — Re-enable a paused webhook

curl -X PATCH "https://api.oec.sh/api/public/v1/webhooks/YOUR_WEBHOOK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

Delete Webhook

DELETE /webhooks/{webhook_id}

Requires full_access key. Returns 204 No Content.

curl -X DELETE "https://api.oec.sh/api/public/v1/webhooks/YOUR_WEBHOOK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Test a Webhook

POST /webhooks/{webhook_id}/test

Sends a synchronous test ping event to the webhook URL and returns the HTTP response. Does not create a delivery log entry. Requires full_access key.

curl -X POST "https://api.oec.sh/api/public/v1/webhooks/YOUR_WEBHOOK_ID/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "status_code": 200,
  "duration_ms": 142,
  "message": null
}

Rotate Signing Secret

POST /webhooks/{webhook_id}/rotate-secret

Generates a new HMAC signing secret. The old secret is immediately invalidated. The new plaintext secret is shown once in the response — store it immediately.

curl -X POST "https://api.oec.sh/api/public/v1/webhooks/YOUR_WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "secret": "whsec_new_secret_here..."
}

Payload Formats

oec.sh can deliver event payloads in four formats. Choose the format that matches your destination when creating or updating a webhook.

raw (default)

The full event envelope is delivered as JSON with the X-OEC-Signature HMAC header. See Signature Verification. This is the most flexible format — you can parse and forward however you like.

{
  "event_id": "evt_01abc123def456",
  "event": "automation_rule.completed",
  "timestamp": "2026-03-15T09:00:00Z",
  "organization_id": "YOUR_ORG_ID",
  "data": {
    "rule_name": "Deploy on push",
    "action_type": "deploy_latest",
    "trigger_type": "push",
    "branch": "main",
    "actor": "jane@example.com"
  }
}

slack

Delivers a Slack Block Kit (opens in a new tab) message directly to a Slack Incoming Webhook URL. The X-OEC-Signature header is not sent for platform formats — Slack handles its own auth.

To use:

1. Create an Incoming Webhook in Slack (your workspace → Apps → Incoming Webhooks)
2. Copy the Webhook URL (https://hooks.slack.com/services/...)
3. Create a webhook on oec.sh with that URL and "format": "slack"

The message includes the event name, a color-coded sidebar (green for success, red for failure), and key details from the event data.

teams

Delivers an Adaptive Card (opens in a new tab) to a Microsoft Teams channel via an Incoming Webhook connector. Set up a Teams Incoming Webhook, paste the URL, and set "format": "teams".

discord

Delivers a rich embed to a Discord channel webhook. In Discord, go to channel Settings → Integrations → Webhooks, create one, and copy the URL. Set "format": "discord".

Receiving Webhooks

Payload Format

oec.sh delivers a POST request to your endpoint with a JSON body:

{
  "event_id": "evt_01abc123def456",
  "event": "deploy.completed",
  "timestamp": "2026-03-13T12:05:00Z",
  "organization_id": "YOUR_ORG_ID",
  "data": {
    "environment_id": "YOUR_ENV_ID",
    "project_id": "YOUR_PROJECT_ID",
    "task_id": "task-uuid",
    "status": "completed",
    "duration_seconds": 300
  }
}

Signature Verification

Every delivery includes an X-OEC-Signature header:

X-OEC-Signature: sha256=<hex_digest>

The signature is an HMAC-SHA256 of the raw request body, signed with your webhook's secret.

Always verify signatures before processing a webhook payload. This prevents bad actors from sending fake events to your endpoint.

import hashlib
import hmac
from fastapi import Request, HTTPException
 
WEBHOOK_SECRET = "whsec_your_secret_here"
 
async def verify_webhook(request: Request) -> bytes:
    body = await request.body()
    signature_header = request.headers.get("X-OEC-Signature", "")
 
    if not signature_header.startswith("sha256="):
        raise HTTPException(status_code=400, detail="Missing signature")
 
    expected_sig = signature_header[len("sha256="):]
    computed_sig = hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256,
    ).hexdigest()
 
    if not hmac.compare_digest(computed_sig, expected_sig):
        raise HTTPException(status_code=401, detail="Invalid signature")
 
    return body

Responding to Webhooks

Your endpoint must respond with an HTTP 2xx status code within 10 seconds. Any non-2xx response or a timeout is recorded as a delivery failure.

Reliability

Retry Logic

If your endpoint returns a non-2xx response or times out, oec.sh retries delivery with exponential backoff:

Auto-Pause on Repeated Failures

After 10 consecutive failed deliveries, the webhook is automatically paused (is_active set to false). You will need to:

1. Fix the issue with your endpoint
2. Re-enable the webhook:

   curl -X PATCH "https://api.oec.sh/api/public/v1/webhooks/YOUR_WEBHOOK_ID" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"is_active": true}'

Delivery Log

GET /webhooks/{webhook_id}/deliveries

Returns the 50 most recent delivery attempts for a webhook, newest first.

[
  {
    "id": "delivery-uuid",
    "event": "deploy.completed",
    "status": "delivered",
    "attempt_count": 1,
    "response_status": 200,
    "response_body": null,
    "error_reason": null,
    "duration_ms": 142,
    "delivered_at": "2026-03-13T12:05:01Z",
    "created_at": "2026-03-13T12:05:00Z"
  }
]

Delivery Object Fields

Mutation Rate Limit

Webhook create, update, and delete operations are rate-limited to 10 mutations per 60-second window per API key. Exceeding this returns 429 Too Many Requests.