Webhooks

The webhook system has three main concepts:

• Notifications — records of events that happen in your organization (e.g. ingestion validated, batch completed). You can list and read these via GET /notifications.
• Webhook subscriptions — URLs you register to receive notifications as HTTP POST requests. Manage these via /webhooks.
• Delivery logs — a record of every HTTP request sent to your webhook URL, including request/response details and retry status. View these via GET /webhooks/:id/deliveries.

You can scope a subscription to specific notification types using resource_type and namespace:

If both are null, the subscription receives all notifications for the organization.

Subscriptions belong to one organization. A parent organization's read access to child data does not make its webhook receive child events; create a subscription in the owning child organization when needed.

You can update filters on an existing subscription via PATCH /webhooks/:id. Changing the url resets verification status — you must verify the new URL before deliveries resume.

The following notifications are emitted by the API:

Additional status notifications use notification.data.event as a machine-readable event name. Filter subscriptions with the resource type and namespace, then branch on data.event in the receiver.

DDS task payloads include operation, status, task_id, record_id, result, and read links. Operations cover record creation, version creation, submission, validation and report rendering. A grouped create finishes when its aggregate task finishes; partial: true identifies partial success. Submission completion and later TRACES reference issuance are separate events, as is readiness of a report re-rendered after references arrive.

Discovery and profile completion are observed by a server-side sweep, independent of customer GET requests. The scheduler runs every minute; notification latency also depends on upstream completion and sweep backlog. A discovery generation event links to partial results; terminal events link to the final status/results. profiling.units.ready means profile the same file again to retrieve refined units; it does not mean new locations were ingested. Expiry events distinguish upstream disappearance or refinement timeout from successful completion.

Checkout paid follows credit application, and refunded follows credit reversal. Identifiers and links are scoped to the owning organization. Attachment stored follows successful storage confirmation; an upload that never confirms remains pending and produces no stored event. Existing ingestion staging/metrics and cadastral notifications continue to use their established payloads.

Summary notifications invalidate cached reads after refresh. They are not a claim that every summary in the organization is ready; use the supplied IDs and fetch the relevant resource. A supplier drain whose affected IDs are not returned emits scope: "organization"; refetch the supplier list for that organization. Ordinary browser/MCP clients still need a receiving service before they can replace polling with webhooks.

Parcel-ingest preparation failures emit parcel.ingest.failed under resource type asset_task, namespace parcel_ingest. Once preparation delegates to the ingestion pipeline, that pipeline retains its existing ingestion events.

When a notification is created, the API sends an HTTP POST to each matching verified subscription. The request includes:

{
  "notification": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Locations validated: 150 features",
    "resource_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
    "resource_type": "asset_task",
    "namespace": "ingestion",
    "data": { "featureCount": 150 }
  },
  "sub": "webhook-subscription-id",
  "iss": "epoch-fm-api",
  "iat": 1773397800,
  "exp": 1773398100
}

Every webhook delivery body is a JWT signed with the subscription's HMAC secret (HS256 algorithm). Verify the body before reading its notification claim.

import { jwtVerify } from "jose";

async function verifyWebhook(request, signingSecret, subscriptionId) {
  const token = await request.text();
  const secret = new TextEncoder().encode(signingSecret);

  const { payload } = await jwtVerify(token, secret, {
    algorithms: ["HS256"],
    issuer: "epoch-fm-api",
    subject: subscriptionId,
  });

  // payload.sub contains the webhook subscription ID
  // payload.iat contains the issued-at timestamp
  return payload;
}

import jwt

def verify_webhook(request, signing_secret, subscription_id):
    token = request.get_data(as_text=True)
    payload = jwt.decode(
        token,
        signing_secret,
        algorithms=["HS256"],
        issuer="epoch-fm-api",
        subject=subscription_id,
    )
    # payload["sub"] contains the webhook subscription ID
    return payload

If your endpoint does not respond with a 2xx status code (or times out), the API retries the delivery with exponential backoff:

There are up to four inline attempts. Each attempt creates a delivery log; the log's next_attempt_at metadata does not imply that a durable retry worker will deliver it later. Inspect GET /webhooks/:id/deliveries for request, response and errors. Delivery remains best effort: keep status GETs as a recovery option after outages or worker termination.

Only active, verified subscriptions are selected for fanout. Receivers should deduplicate by notification.id; new status producers also use a scoped notification_key receipt to suppress repeated observations while that notification record exists. Concurrent emitters lease the receipt while delivering; an abandoned claim can be recovered after five minutes. This receipt does not make state changes and event creation atomic.

Each delivery attempt is recorded with full request and response details:

If your signing secret is compromised, rotate it immediately:

curl -X POST https://api.epoch.blue/webhooks/{id}/rotate-secret \
  -H "x-api-key: sk-epoch-..."

The old secret is invalidated immediately — there is no grace period. The response contains the new secret in plain text. Update your endpoint's verification logic with the new secret before processing any further deliveries.

• Respond quickly — return a 200 within 10 seconds. Do heavy processing asynchronously.
• Handle duplicates — use the notification id to deduplicate, as retries may deliver the same notification more than once.
• Monitor delivery logs — check GET /webhooks/:id/deliveries periodically to catch failures early.
• Use filters — scope subscriptions to specific resource_type and namespace values to reduce noise.