Create Webhook

POST {{BASE_HABITAT_URL}}/api/webhooks

Required scope: webhooks:write

Registers a webhook destination for your operator. First sends JSON POST requests when matching order lifecycle statuses or opted-in events occur.

Body

Field	Type	Required	Notes
url	string (HTTPS URI)	Yes	Destination URL. A literal $ is replaced with the order’s externalId at send time. Use HTTPS and avoid secrets in the URL.
event_filter	array | null	No	Lifecycle status_v3 values plus event keys "ready_now" and "Refunded". null or omitted receives all events; an empty array receives none.
active	boolean	No	Defaults to true. Set to false to pause delivery without deleting configuration.
description	string | null	No	Human-readable label shown in Dispatch.
http_options.headers	object	No	Private headers sent with every delivery. Values are encrypted at rest and masked by List Webhooks. This is the supported place for receiver authentication.

Recommended configuration

• Use a dedicated endpoint and rotating bearer token or shared secret in http_options.headers.
• Subscribe only to events your consumer handles.
• Return 2xx quickly after durable enqueue; process asynchronously.
• Implement durable idempotency and periodic order reconciliation.
• Sending event_filter: ["ready_now"] receives only the Ready Now event. The payload keeps the order’s current status_v3 and adds event: "ready_now" plus readyAt.

Unknown fields are rejected with 400. See Webhook Events for payload examples and delivery behavior.

Request body

{
    "url": "https://my-api.example.com/first-delivery/webhook",
    "description": "Production order event consumer",
    "active": true,
    "event_filter": [
        "scheduled",
        "ready_now",
        "en_route_pickup",
        "arrived_pickup",
        "en_route_dropoff",
        "arrived_dropoff",
        "completed",
        "cancelled",
        "reassign",
        "Refunded"
    ],
    "http_options": {
        "headers": {
            "Authorization": "Bearer YOUR_SERVER_TOKEN"
        }
    }
}

Examples

cURL

curl --request POST '${BASE_HABITAT_URL}/api/webhooks' \
  --data '{
    "url": "https://my-api.example.com/first-delivery/webhook",
    "description": "Production order event consumer",
    "active": true,
    "event_filter": [
        "scheduled",
        "ready_now",
        "en_route_pickup",
        "arrived_pickup",
        "en_route_dropoff",
        "arrived_dropoff",
        "completed",
        "cancelled",
        "reassign",
        "Refunded"
    ],
    "http_options": {
        "headers": {
            "Authorization": "Bearer YOUR_SERVER_TOKEN"
        }
    }
}'

Node.js

const response = await fetch("${BASE_HABITAT_URL}/api/webhooks", {
  "method": "POST",
  "headers": {},
  "body": "{\n    \"url\": \"https://my-api.example.com/first-delivery/webhook\",\n    \"description\": \"Production order event consumer\",\n    \"active\": true,\n    \"event_filter\": [\n        \"scheduled\",\n        \"ready_now\",\n        \"en_route_pickup\",\n        \"arrived_pickup\",\n        \"en_route_dropoff\",\n        \"arrived_dropoff\",\n        \"completed\",\n        \"cancelled\",\n        \"reassign\",\n        \"Refunded\"\n    ],\n    \"http_options\": {\n        \"headers\": {\n            \"Authorization\": \"Bearer YOUR_SERVER_TOKEN\"\n        }\n    }\n}"
})
const data = await response.json()

Python

import requests

response = requests.request(
    "POST",
    "${BASE_HABITAT_URL}/api/webhooks",
    headers={},
    data="{\n    \"url\": \"https://my-api.example.com/first-delivery/webhook\",\n    \"description\": \"Production order event consumer\",\n    \"active\": true,\n    \"event_filter\": [\n        \"scheduled\",\n        \"ready_now\",\n        \"en_route_pickup\",\n        \"arrived_pickup\",\n        \"en_route_dropoff\",\n        \"arrived_dropoff\",\n        \"completed\",\n        \"cancelled\",\n        \"reassign\",\n        \"Refunded\"\n    ],\n    \"http_options\": {\n        \"headers\": {\n            \"Authorization\": \"Bearer YOUR_SERVER_TOKEN\"\n        }\n    }\n}",
)
response.raise_for_status()

Saved responses

200 all webhooks to basic URL

{
    "type": "success",
    "webhook": {
        "id": "30202232-d3ae-4840-ab20-d6cb5a379b95",
        "created_at": "2023-03-17 17:51:42.790555+00",
        "operator_id": 1,
        "url": "https://webhooks.firstdelivery.com",
        "http_options": null,
        "active": true,
        "event_filter": null
    }
}

200 with external ID in URL ($)

{
    "type": "success",
    "webhook": {
        "id": "42e1f7b7-09db-4008-8a77-8729f549c922",
        "created_at": "2023-03-17 18:14:08.707849+00",
        "event_filter": null,
        "url": "https://webhooks.firstdelivery.com/orders/${ORDER_ID}",
        "active": true,
        "http_options": {}
    }
}

200 on select events

{
    "type": "success",
    "webhook": {
        "id": "885af834-36a9-46ce-a9cc-8cb9ee196732",
        "created_at": "2023-03-17 17:52:58.984459+00",
        "operator_id": 1,
        "url": "https://webhooks.firstdelivery.com",
        "http_options": null,
        "active": true,
        "event_filter": [
            "cancelled"
        ]
    }
}

200 with auth headers

{
    "type": "success",
    "webhook": {
        "id": "071c80b3-39e0-4c99-81f2-4703668bfcde",
        "created_at": "2023-03-17 18:09:07.556135+00",
        "event_filter": null,
        "url": "https://webhooks.firstdelivery.com",
        "active": true,
        "http_options": {
            "headers": {
                "Authorization": "YOUR_SERVER_ACCESS_TOKEN"
            }
        }
    }
}