Documentation menu
Docs / Developers / Webhooks

Webhooks

Receive signed JSON notifications when data changes or a job finishes. Events contain ids and links; fetch the current data with your API key.

Create a subscription#

In Admin → Integrations → Webhooks, or with a read_write key, create a subscription using POST /v1/webhooks:

{
  "name": "Dataset sync",
  "url": "https://hooks.example.com/orbgis",
  "events": ["layer.data_changed", "job.completed", "job.failed"]
}

Add itemId to follow one item. Save the returned secret: it is shown only once. Subscriptions accept exact event names, not wildcards. At most 20 active webhooks are allowed per organization.

Events#

EventWhenData fields
layer.data_changedLayer data changes; coalesced per layer over about ten seconds.collectionId, itemId
job.completedAn ingest or export succeeds.jobId, kind, status, itemId, collectionId
job.failedA job fails or is cancelled.Same job fields.
item.createdA content item is created.itemId, type
item.updatedItem metadata, ownership, folder or publication changes; coalesced over about ten seconds. Content edits do not trigger this event.itemId, type
item.trashedAn item moves to the recycle bin; sent before it becomes unavailable.itemId, type
item.restoredAn item is restored.itemId, type
survey.response_submittedA survey receives a response. Read it at /collections/{collectionId}/items/{objectid}.surveyId, objectid, itemId, collectionId
pingYou request a test delivery.Empty object.

Access and delivery#

Events are delivered only when the subscription’s owner can see the affected item. The owner is the integration whose key created the subscription, or the person who created it in the portal. Job events go only to the job’s creator. Disabling an integration stops its deliveries.

Use an HTTPS URL with a hostname. Private addresses, IP literals and OrbGIS domains are refused. Deliveries are POST requests with a ten-second deadline; redirects count as failures. Return 2xx quickly and process the event afterwards.

Verify the signature#

The body includes id, type, createdAt, orgId, deliveryId, attempt, data and links. Headers include X-OrbGIS-Event, X-OrbGIS-Delivery and X-OrbGIS-Signature.

  1. Keep the raw body

    Verify the exact bytes received before parsing JSON. Re-serializing the body changes the signature.

  2. Compute and compare

    Parse X-OrbGIS-Signature: t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256 with your secret over t + "." + raw body and compare the hex digest with v1 using a constant-time comparison.

  3. Check age and duplicates

    Reject timestamps more than five minutes from your clock. Deduplicate by X-OrbGIS-Delivery, which stays the same across retries.

Complete Python and Node receiver examples are available from OrbGIS on request.

Retries and recovery#

Failed deliveries retry after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours, then become dead. Delivery is at least once, so duplicates are possible. After 20 consecutive failures, the subscription is disabled. Fix the endpoint, then enable it to reset the counter.

RouteUse
GET /v1/webhooks/{id}/deliveriesInspect attempts, HTTP status and timing for the last 30 days.
POST /v1/webhooks/{id}/pingSend a signed test event.
PATCH /v1/webhooks/{id}Change the subscription or set active to pause or resume.
POST /v1/webhooks/{id}/rotate-secretIssue a new signing secret.
DELETE /v1/webhooks/{id}Delete the subscription.