Webhooks

Signed notifications to your system when something happens in your company.

Create a webhook endpoint

POSThttps://api.drometra.com/v1/webhooks/endpoints

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.
idempotency-keymandatorystring · uuid: A new UUID per operation. If you repeat the request with the same key, the change is not applied twice.

Body

urlmandatorystring
descriptionstring
eventTypesmandatoryarray de enum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …

Response · 201

objectalways
object

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X POST "https://api.drometra.com/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \ -d '{
    "url": "…",
    "eventTypes": []
  }'

response · 201

{
  "endpoint": {
    "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
    "url": "…",
    "description": "…",
    "eventTypes": [
      "distribution.order.created"
    ],
    "state": "active",
    "disabledReason": "manual",
    "consecutiveFailures": 0,
    "version": 1,
    "createdAt": "2026-10-21T14:02:31Z",
    "updatedAt": "2026-10-21T14:02:31Z",
    "secrets": [
      {
        "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
        "createdAt": "2026-10-21T14:02:31Z",
        "expiresAt": "2026-10-21T14:02:31Z"
      }
    ]
  },
  "secret": {
    "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
    "value": "…",
    "createdAt": "2026-10-21T14:02:31Z"
  }
}

List webhook endpoints

GEThttps://api.drometra.com/v1/webhooks/endpoints

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.

Response · 200

array de objectalways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X GET "https://api.drometra.com/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "Accept: application / json"

response · 200

{
  "items": [
    {
      "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "url": "…",
      "description": "…",
      "eventTypes": [
        "distribution.order.created"
      ],
      "state": "active",
      "disabledReason": "manual",
      "consecutiveFailures": 0,
      "version": 1,
      "createdAt": "2026-10-21T14:02:31Z",
      "updatedAt": "2026-10-21T14:02:31Z",
      "secrets": [
        {
          "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
          "createdAt": "2026-10-21T14:02:31Z",
          "expiresAt": "2026-10-21T14:02:31Z"
        }
      ]
    }
  ]
}

Get a webhook endpoint

GEThttps://api.drometra.com/v1/webhooks/endpoints/{id}

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Response · 200

idstring · uuidalways
urlstringalways
descriptionstring · nullalways
eventTypesarray de enum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …always
stateenum: active | disabledalways
disabledReasonenum: manual | failures | always
consecutiveFailuresintegeralways
versionintegeralways
createdAtstring · date-timealways
updatedAtstring · date-timealways
array de objectalways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X GET "https://api.drometra.com/v1/webhooks/endpoints/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "Accept: application / json"

response · 200

{
  "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "url": "…",
  "description": "…",
  "eventTypes": [
    "distribution.order.created"
  ],
  "state": "active",
  "disabledReason": "manual",
  "consecutiveFailures": 0,
  "version": 1,
  "createdAt": "2026-10-21T14:02:31Z",
  "updatedAt": "2026-10-21T14:02:31Z",
  "secrets": [
    {
      "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "createdAt": "2026-10-21T14:02:31Z",
      "expiresAt": "2026-10-21T14:02:31Z"
    }
  ]
}

Update a webhook endpoint

PATCHhttps://api.drometra.com/v1/webhooks/endpoints/{id}

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Body

versionmandatoryinteger
descriptionstring · null
eventTypesarray de enum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …
activeboolean

Response · 200

idstring · uuidalways
urlstringalways
descriptionstring · nullalways
eventTypesarray de enum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …always
stateenum: active | disabledalways
disabledReasonenum: manual | failures | always
consecutiveFailuresintegeralways
versionintegeralways
createdAtstring · date-timealways
updatedAtstring · date-timealways
array de objectalways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X PATCH "https://api.drometra.com/v1/webhooks/endpoints/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "Content-Type: application/json" \ -d '{
    "version": 0
  }'

response · 200

{
  "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "url": "…",
  "description": "…",
  "eventTypes": [
    "distribution.order.created"
  ],
  "state": "active",
  "disabledReason": "manual",
  "consecutiveFailures": 0,
  "version": 1,
  "createdAt": "2026-10-21T14:02:31Z",
  "updatedAt": "2026-10-21T14:02:31Z",
  "secrets": [
    {
      "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "createdAt": "2026-10-21T14:02:31Z",
      "expiresAt": "2026-10-21T14:02:31Z"
    }
  ]
}

Rotate the signing secret

POSThttps://api.drometra.com/v1/webhooks/endpoints/{id}/secrets

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.
idempotency-keymandatorystring · uuid: A new UUID per operation. If you repeat the request with the same key, the change is not applied twice.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Body

versionmandatoryinteger
graceSecondsmandatoryinteger

Response · 201

objectalways
object

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X POST "https://api.drometra.com/v1/webhooks/endpoints/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d/secrets" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \ -d '{
    "version": 0,
    "graceSeconds": 0
  }'

response · 201

{
  "endpoint": {
    "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
    "url": "…",
    "description": "…",
    "eventTypes": [
      "distribution.order.created"
    ],
    "state": "active",
    "disabledReason": "manual",
    "consecutiveFailures": 0,
    "version": 1,
    "createdAt": "2026-10-21T14:02:31Z",
    "updatedAt": "2026-10-21T14:02:31Z",
    "secrets": [
      {
        "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
        "createdAt": "2026-10-21T14:02:31Z",
        "expiresAt": "2026-10-21T14:02:31Z"
      }
    ]
  },
  "secret": {
    "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
    "value": "…",
    "createdAt": "2026-10-21T14:02:31Z"
  }
}

Send a test event

POSThttps://api.drometra.com/v1/webhooks/endpoints/{id}/test

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.
idempotency-keymandatorystring · uuid: A new UUID per operation. If you repeat the request with the same key, the change is not applied twice.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Response · 202

idstring · uuidalways
endpointIdstring · uuidalways
eventIdstring · uuidalways
eventTypeenum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …always
stateenum: pending | delivering | succeeded | deadalways
modeenum: auto | manualalways
attemptsintegeralways
maxAttemptsintegeralways
manualRetriesintegeralways
nextAttemptAtstring · null · date-timealways
lastAttemptAtstring · null · date-timealways
lastStatusinteger · nullalways
lastOutcomeenum: success | http_status | timeout | dns_failure | destination_blocked | tls_failure | …always
succeededAtstring · null · date-timealways
deadAtstring · null · date-timealways
createdAtstring · date-timealways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X POST "https://api.drometra.com/v1/webhooks/endpoints/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d/test" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Accept: application / json"

response · 202

{
  "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "endpointId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "eventId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "eventType": "distribution.order.created",
  "state": "pending",
  "mode": "auto",
  "attempts": 15,
  "maxAttempts": 15.5,
  "manualRetries": 5,
  "nextAttemptAt": "2026-10-21T14:02:31Z",
  "lastAttemptAt": "2026-10-21T14:02:31Z",
  "lastStatus": 349.5,
  "lastOutcome": "success",
  "succeededAt": "2026-10-21T14:02:31Z",
  "deadAt": "2026-10-21T14:02:31Z",
  "createdAt": "2026-10-21T14:02:31Z"
}

List an endpoint's deliveries

GEThttps://api.drometra.com/v1/webhooks/endpoints/{id}/deliveries

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Reference parameters

stateenum: pending | delivering | succeeded | dead
beforestring · uuid
limitinteger

Response · 200

array de objectalways
nextCursorstring · null · uuidalways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X GET "https://api.drometra.com/v1/webhooks/endpoints/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d/deliveries" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "Accept: application / json"

response · 200

{
  "items": [
    {
      "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "endpointId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "eventId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "eventType": "distribution.order.created",
      "state": "pending",
      "mode": "auto",
      "attempts": 15,
      "maxAttempts": 15.5,
      "manualRetries": 5,
      "nextAttemptAt": "2026-10-21T14:02:31Z",
      "lastAttemptAt": "2026-10-21T14:02:31Z",
      "lastStatus": 349.5,
      "lastOutcome": "success",
      "succeededAt": "2026-10-21T14:02:31Z",
      "deadAt": "2026-10-21T14:02:31Z",
      "createdAt": "2026-10-21T14:02:31Z"
    }
  ],
  "nextCursor": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d"
}

List webhook deliveries

GEThttps://api.drometra.com/v1/webhooks/deliveries

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.

Reference parameters

stateenum: pending | delivering | succeeded | dead
beforestring · uuid
limitinteger
endpointIdstring · uuid

Response · 200

array de objectalways
nextCursorstring · null · uuidalways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X GET "https://api.drometra.com/v1/webhooks/deliveries" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "Accept: application / json"

response · 200

{
  "items": [
    {
      "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "endpointId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "eventId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
      "eventType": "distribution.order.created",
      "state": "pending",
      "mode": "auto",
      "attempts": 15,
      "maxAttempts": 15.5,
      "manualRetries": 5,
      "nextAttemptAt": "2026-10-21T14:02:31Z",
      "lastAttemptAt": "2026-10-21T14:02:31Z",
      "lastStatus": 349.5,
      "lastOutcome": "success",
      "succeededAt": "2026-10-21T14:02:31Z",
      "deadAt": "2026-10-21T14:02:31Z",
      "createdAt": "2026-10-21T14:02:31Z"
    }
  ],
  "nextCursor": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d"
}

Get a webhook delivery

GEThttps://api.drometra.com/v1/webhooks/deliveries/{id}

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Response · 200

idstring · uuidalways
endpointIdstring · uuidalways
eventIdstring · uuidalways
eventTypeenum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …always
stateenum: pending | delivering | succeeded | deadalways
modeenum: auto | manualalways
attemptsintegeralways
maxAttemptsintegeralways
manualRetriesintegeralways
nextAttemptAtstring · null · date-timealways
lastAttemptAtstring · null · date-timealways
lastStatusinteger · nullalways
lastOutcomeenum: success | http_status | timeout | dns_failure | destination_blocked | tls_failure | …always
succeededAtstring · null · date-timealways
deadAtstring · null · date-timealways
createdAtstring · date-timealways
objectalways
array de objectalways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X GET "https://api.drometra.com/v1/webhooks/deliveries/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "Accept: application / json"

response · 200

{
  "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "endpointId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "eventId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "eventType": "distribution.order.created",
  "state": "pending",
  "mode": "auto",
  "attempts": 15,
  "maxAttempts": 15.5,
  "manualRetries": 5,
  "nextAttemptAt": "2026-10-21T14:02:31Z",
  "lastAttemptAt": "2026-10-21T14:02:31Z",
  "lastStatus": 349.5,
  "lastOutcome": "success",
  "succeededAt": "2026-10-21T14:02:31Z",
  "deadAt": "2026-10-21T14:02:31Z",
  "createdAt": "2026-10-21T14:02:31Z",
  "event": {
    "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
    "type": "distribution.order.created",
    "occurredAt": "2026-10-21T14:02:31Z",
    "data": {}
  },
  "attemptLog": [
    {
      "attemptNo": 15.5,
      "trigger": "auto",
      "startedAt": "2026-10-21T14:02:31Z",
      "durationMs": 30000,
      "outcome": "success",
      "statusCode": 349.5
    }
  ]
}

Retry a delivery

POSThttps://api.drometra.com/v1/webhooks/deliveries/{id}/retry

Requires the access token of a person in your company.

Headers

x-tenant-idmandatorystring · uuid: Your company's identifier. The server checks that you are still an active member of it.
idempotency-keymandatorystring · uuid: A new UUID per operation. If you repeat the request with the same key, the change is not applied twice.

Road parameters

idmandatorystring · uuid: e. g. 0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d

Response · 202

idstring · uuidalways
endpointIdstring · uuidalways
eventIdstring · uuidalways
eventTypeenum: distribution.order.created | distribution.order.cancelled | routing.plan.approved | field.route.assigned | field.route.cancelled | field.route.started | …always
stateenum: pending | delivering | succeeded | deadalways
modeenum: auto | manualalways
attemptsintegeralways
maxAttemptsintegeralways
manualRetriesintegeralways
nextAttemptAtstring · null · date-timealways
lastAttemptAtstring · null · date-timealways
lastStatusinteger · nullalways
lastOutcomeenum: success | http_status | timeout | dns_failure | destination_blocked | tls_failure | …always
succeededAtstring · null · date-timealways
deadAtstring · null · date-timealways
createdAtstring · date-timealways

It can respond with error 400, 401, 403, 404, 409, 410, 413, 415, 422, 429, 503. The error body is explained in Concepts.

request

curl -X POST "https://api.drometra.com/v1/webhooks/deliveries/0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d/retry" \
  -H "Authorization: Bearer $DROMETRA _ TOKEN"\
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Accept: application / json"

response · 202

{
  "id": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "endpointId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "eventId": "0b6f8c2e-4a1d-4e5b-9c3f-2d7e8a9b1c4d",
  "eventType": "distribution.order.created",
  "state": "pending",
  "mode": "auto",
  "attempts": 15,
  "maxAttempts": 15.5,
  "manualRetries": 5,
  "nextAttemptAt": "2026-10-21T14:02:31Z",
  "lastAttemptAt": "2026-10-21T14:02:31Z",
  "lastStatus": 349.5,
  "lastOutcome": "success",
  "succeededAt": "2026-10-21T14:02:31Z",
  "deadAt": "2026-10-21T14:02:31Z",
  "createdAt": "2026-10-21T14:02:31Z"
}