Webhooks API

Webhooks fire outgoing HTTP POST requests to your endpoint when platform events occur - sandbox lifecycle changes, deployment completions, billing events, and more. Each delivery is signed with HMAC-SHA256 so you can verify authenticity.

Base path: /api/v1/webhooks

Endpoints

List Webhooks

GET /api/v1/webhooks

Auth

Authorization: Bearer msk_...

Response - 200 OK

{
  "data": [
    {
      "id": "wh_01hwxyz...",
      "name": "My Webhook",
      "url": "https://api.myapp.com/hooks/miosa",
      "events": ["sandbox.created", "sandbox.destroyed"],
      "secret_preview": "sk_live_••••••••abcd",
      "retry_count": 3,
      "created_at": "2026-05-01T00:00:00Z",
      "updated_at": "2026-05-01T00:00:00Z"
    }
  ]
}

Create a Webhook

POST /api/v1/webhooks

Request Body

{
  "url": "https://api.myapp.com/hooks/miosa",
  "name": "Sandbox lifecycle",
  "events": ["sandbox.created", "sandbox.ready", "sandbox.error", "sandbox.destroyed"],
  "retry_count": 3
}

Response - 201 Created

{
  "data": {
    "id": "wh_01hwxyz...",
    "name": "Sandbox lifecycle",
    "url": "https://api.myapp.com/hooks/miosa",
    "events": ["sandbox.created", "sandbox.ready", "sandbox.error", "sandbox.destroyed"],
    "secret": "sk_live_abc123def456...",
    "secret_preview": "sk_live_••••••••3456",
    "retry_count": 3,
    "created_at": "2026-05-26T10:14:23Z",
    "updated_at": "2026-05-26T10:14:23Z"
  }
}

The secret field appears only in this response. Save it securely.

Update a Webhook

PATCH /api/v1/webhooks/{id}

Partial update - include only fields you want to change.

Request Body

Same fields as create, all optional.

Response - 200 OK

Webhook object without the secret field.

Delete a Webhook

DELETE /api/v1/webhooks/{id}

Response - 204 No Content

Send a Test Delivery

POST /api/v1/webhooks/{id}/test

Sends a synthetic webhook.test event to the configured URL to verify connectivity and signature verification.

The attempt is recorded in the delivery log like any other delivery, marked as a test, so what the endpoint received is always visible at GET /api/v1/webhooks/{id}/deliveries. A test does not count toward retry_count and never moves the webhook to failed: a test against an endpoint that is temporarily down must not pause a live subscription.

Response - 200 OK

{
  "delivered": true,
  "status_code": 200,
  "duration_ms": 143
}

List Deliveries

GET /api/v1/webhooks/{id}/deliveries

Returns recent delivery attempts with status codes and timing.

Response - 200 OK

{
  "data": [
    {
      "id": "del_01hwyza...",
      "event_type": "sandbox.ready",
      "status": "delivered",
      "status_code": 200,
      "attempt": 1,
      "duration_ms": 98,
      "delivered_at": "2026-05-26T10:14:24Z"
    },
    {
      "id": "del_01hwyzb...",
      "event_type": "sandbox.created",
      "status": "failed",
      "status_code": 500,
      "attempt": 3,
      "duration_ms": 5012,
      "delivered_at": "2026-05-26T10:14:20Z"
    }
  ]
}

Signature Verification

Every delivery includes an X-Miosa-Signature header. Verify it on your server before trusting the payload:

X-Miosa-Signature: sha256=<hex_digest>

Compute the expected signature:

hmac = HMAC-SHA256(secret, raw_request_body_bytes)
expected = "sha256=" + hex(hmac)
assert constant_time_equals(expected, request.headers["X-Miosa-Signature"])

Example verification (Python)

import hmac, hashlib

def verify_signature(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Example verification (TypeScript)

import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(secret: string, body: Buffer, header: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Retry Policy

Failed deliveries are retried on a fixed backoff schedule:

MIOSA makes up to eight delivery attempts over roughly 15.5 hours (within a 24-hour window), then drops the event.

A delivery is considered failed if your endpoint returns a non-2xx status code or does not respond within 10 seconds. retry_count (0-10, default 3) is the number of consecutive failed deliveries after which MIOSA marks the webhook failed; it is not the per-delivery retry cap. Set it to 0 to mark the webhook failed on the first failed delivery.

Subscribed Event Types

GET /api/v1/webhooks/events returns this list, grouped by product surface. It is the same list the API validates a subscription against, so an event that is not here cannot be subscribed to.

forge.* payloads carry repository_id, repository_slug and organization_slug, so one subscription can route each event to the right repository.

webhook.test is the synthetic event sent by POST /api/v1/webhooks/:id/test. It is not subscribable and appears in the delivery log as a test delivery.

Subscribe to all events by omitting the events field. Subscribe to a subset by listing specific event types.

Examples