Skip to content

Webhooks ​

Without webhooks we find changed orders by reading /v1/orders?updatedSince=… every few minutes. With the webhooks capability you call us as soon as an order changes, with nothing but its id, and we fetch the order from you with GET /v1/orders/{id}. Polling keeps running as a safety net, unless you turn it off with orders.reconciliation.enabled, so a webhook that never arrives costs minutes, not data. With webhooks you can raise orders.reconciliation.minDelay to poll less often.

Delivery ​

json
{
  "order": { "id": "ord_991" }
}

Then we call you: GET /v1/orders/ord_991, which answers with the same record as one entry of /v1/orders.

Payload

Send POST with { "order": { "id": … } } to the URL of the organiser's integration whenever an order's updatedAt moves: a new order, a payment, a refund, a new holder. We ignore everything else in the body, so a payload you already send elsewhere works too, as long as it has order.id.

Authentication

The URL is unique per integration, and we never trust what a webhook says: we always fetch the order ourselves, with the organiser's API key as the bearer token. Calling the URL with an order id from another account gets nothing in.

Duplicates

We always fetch the current state, so the same order twice, or two changes in the wrong order, give the same result. We answer 2xx within milliseconds. Retrying a failed call is welcome but not required.

Registration ​

You choose, in capabilities.webhooks.setup.

  • "manual": After connecting, the Innercrowd dashboard shows the organiser their webhook URL. They paste it into your back office, wherever you let them configure an order webhook. Nothing to build beyond sending the call.
  • "managed": We register the URL through your API when the organiser connects, and remove it when they disconnect. No copying for the organiser, and the URL can't end up wrong.
EndpointDoesAnswers
GET /v1/orders/{id}One order, as one record of /v1/orders. Required for webhooks.200 with the record. 404 when the account has no such order; we ignore that webhook.
POST /v1/webhooks/upsertRegisters our URL, or updates it, under our id. Only for "managed".200. We call it on every connect, so it must be safe to repeat.
POST /v1/webhooks/deleteRemoves the webhook. We send both our id and the URL, so you can match on whichever you stored. Only for "managed".204, also when it no longer exists.
json
{
  "webhook": {
    "id": "5e0b9a7d-…",
    "url": "https://api.innercrowd.io/api/v1/webhooks/innercrowd-connect/2d7c4e1a-…/orders"
  }
}
json
{
  "webhook": {
    "id": "5e0b9a7d-…",
    "url": "https://api.innercrowd.io/api/v1/webhooks/innercrowd-connect/2d7c4e1a-…/orders"
  }
}

Configuration ​

In capabilities.webhooks of /v1/account.

OptionTypeDefaultWhat it does
versionstring"v1"The version you implement, and the prefix of the paths we call.
setupstringrequired"manual": the organiser pastes our URL into your back office. "managed": we register it with /v1/webhooks/upsert.