Webhook events

Makini pushes signed JSON events to your HTTPS endpoint as things happen: a connection is created or changes, a sync finishes, records appear or change in the connected system. Pair them with the API and your product stays current without polling.

Events

Event	Sent when
`connection.created`	A connection is created, including one that is still waiting for its credentials.
`connection.updated`	A connection changes: new credentials, a new name or metadata, a reconnect.
`connection.deleted`	A connection is deleted. `data.deleted` is `soft` or `force`.
`connection.deactivated`	A connection is switched off. It stops syncing and serving data until it is switched on again.
`connection.reactivated`	A switched-off connection is switched on again.
`connection.credentials_expired`	The connected system refused the stored credentials. Syncing has stopped until new credentials are supplied. Sent once, on the first refusal.
`sync.completed`	A sync run finishes. `data.status` is `success` or `failed`, so you can alert on either.
`entity.detected`	A sync brought in records Makini has not seen before.
`entity.updated`	A sync brought in changes to records Makini already had.

Entity events can be limited to the entity types you choose on the endpoint (entityTypes, such as WorkOrder and Asset); connection and sync events are never filtered by it.

The envelope

Every delivery body has the same five fields:

Field	Meaning
`id`	The event's unique id. It is also the `X-Makini-Delivery` header, and it stays the same on every retry.
`type`	The event name, such as `sync.completed`. Also sent as the `X-Makini-Event` header.
`occurredAt`	When Makini recorded the event (RFC 3339, UTC).
`source`	Always `management-api`.
`data`	The event's payload, shown below.

Payloads

connection.*

sync.completed

entity.* (batched)

entity.* (one per record)

Every connection event carries the connection as it is after the change. connection.deleted adds deleted.

{
  "id": "5b0d7c52-2f9e-4d0b-9a57-1c3e8f6a2d41",
  "type": "connection.updated",
  "occurredAt": "2026-09-25T09:41:07.512Z",
  "source": "management-api",
  "data": {
    "connection": {
      "id": "0192f3a1-7c2e-7b10-9d4e-5f1a2b3c4d5e",
      "clientId": "9e8d7c6b-5a49-4382-a1b0-c9d8e7f6a5b4",
      "name": "Plant 4 fleet",
      "email": "ops@customer.example",
      "platform": "fleetio",
      "adapterSlug": "fleetio",
      "userMetadata": { "customerId": "cus_8812" },
      "connectedAt": "2026-09-20T14:02:11.000Z",
      "deactivatedAt": null,
      "credentialsExpiredAt": null,
      "mcpUserId": null,
      "egressProfileId": null,
      "createdAt": "2026-09-20T13:58:40.000Z",
      "updatedAt": "2026-09-25T09:41:07.000Z"
    }
  }
}

userMetadata holds the metadata you attached when the connection was created, so you can tie the event back to your own customer.

An entity's entityType is its schema name in the API Reference, and id is the Makini id: pass it to GET /v4/<entity>/{id} for the full record.

Add an endpoint

Open the webhooks settings

In the dashboard, go to Settings → Webhooks and click Add webhook.

Enter your endpoint URL

Use an https:// URL. Plain http:// is accepted for localhost while you develop. Makini checks the address when you save and again before every delivery, and never sends to private or reserved network addresses.

Choose the events

Tick the events under Send events for: connections, syncs, entities, or any mix.

Choose the connections

Keep All connections, or pick Selected connections and choose the ones this endpoint serves.

Choose the entities

With an entity event ticked, keep All entities or pick Selected entities and choose the entity types this endpoint receives.

Set delivery

Under Delivery, choose how entity events are grouped (Records) and the Retry policy. See Verifying webhooks for the retry schedules.

Save and store the secret

Click Add webhook. The signing secret is shown only once: copy it into your secret store now. Your receiver uses it to verify every delivery.

To change an endpoint later, click its edit icon. Switch off Active to pause it: an inactive webhook keeps its settings and its secret but receives nothing.

Least privilege by design. Endpoints are managed by your team in the dashboard, not by API tokens, so no token can ever redirect your events to a new address.

Batched or one per record

The Records setting shapes entity events only:

Batched (default): up to 100 records per request, under data.entities. Fewer requests for a busy sync.

One per record: a separate request for every record, under data.entity. Simplest when each record drives its own job.

Connection and sync events always arrive one event per request.

Scope an endpoint to connections

With Selected connections, an endpoint receives events only for the connections you chose. Use it to route each customer's events to their own receiver, or to keep a test endpoint on test connections. All connections includes every connection created later.

The initial pull, then incremental reads

A connection's first successful sync brings in everything, so it sends sync.completed with firstSuccess: true and no entity events. Read that first load straight from the API instead: it's faster and it's complete.

Initial pull

On sync.completed with status: "success" and firstSuccess: true, page through each list endpoint you need, such as GET /v4/work-orders, without updatedSince. Use a connection-scoped token for data.connectionId (see Access tokens).

Keep a cursor

Store the event's startedAt as that connection's cursor.

Read what changed

On every later successful sync.completed, read each list with updatedSince=<cursor>, then move the cursor to this event's startedAt.

Reading from the previous run's start means a missed event never leaves a gap, and re-reading a record is harmless: its id never changes, so you upsert by it.

Entity events tell you which records moved, as they move: use them to trigger work right away. The updatedSince read is your complete, ordered record of every change. Most integrations use both.

Verify signatures, deduplicate and choose a retry policy: see Verifying webhooks.

Control how often syncs run: see Sync schedules.

Webhook events

Events#

The envelope#

Payloads#

Add an endpoint#

Batched or one per record#

Scope an endpoint to connections#

The initial pull, then incremental reads#

Next#

Events

The envelope

Payloads

Add an endpoint

Batched or one per record

Scope an endpoint to connections

The initial pull, then incremental reads

Next