Public documentation and examples for the webhooks your Trebu app sends to client endpoints.
\nπ Authentication
\nDefault header: Authorization: Api-Key REPLACE_ME
Content-Type: application/json
β±οΈ Timeouts & Retries
\nTrebu times out requests after 30 seconds.
\nRetries up to 3 times on network errors/timeouts with exponential backoff (β2s β 4s β 8s).
\nβ Receiver Expectations
\nRespond with HTTP 2xx as quickly as possible (ideally < 5s).
\nPrefer JSON body with success status: { \"success\": true }.
NonβJSON is accepted but discouraged; Trebu will capture status and first 200 chars of text.
\nThis collection demonstrates Trebu's webhook event envelope and sample events for logistics tendering.
Use these requests to validate your endpoint and to learn the payload shapes you will receive in production.
Sends realistic webhook payloads to your {{callback_url}} with Authorization: Api-Key {{api_key}}.
Uses a consistent envelope: { \"event\", \"data\" }.
Implements a minimal viable set of domain events for tendering: load auctions, loads, and bid requests.
\nProvides schema fields designed to be forward-compatible: version, schema_version, occurred_at, aggregate, related, payload.
Each Trebu client can register one webhook callback URL at a time. This ensures consistent ordering and simplifies operational controls (retries, backoff, dead-letter handling).
\nIf you attempt to set a different callback URL while one already exists, Trebu will replace the previous URL (or reject the change if your tenant enforces admin-only changes).
\nAll events for that client will be delivered to the single configured URL.
\nFor multi-environment setups (e.g., staging vs prod), create separate clients and configure a callback URL per client.
\nRecommended documentation snippet you can show to your integrators:
\n\n\nWebhook callback URL
\n
Trebu delivers all webhook events for your client to a single HTTPS endpoint. Configure this under Settings β Webhooks. If you need multiple destinations, relay events from your endpoint to downstream services. To change the URL, update it in settings; the previous URL will stop receiving events immediately after the change is saved.
HTTP header: Authorization: Api-Key
Keep your API key secret; rotate regularly.
\nOptionally, enable IP allowlists and (future) message signatures.
\nDelivery is at-least-once.
\nDeduplicate by data.id.
Respond quickly (β€3s). Use asynchronous processing on your side.
\nversion β semantic event versioning (business meaning)
schema_version β JSON structure version (MVP: 1)
Set {{callback_url}} to your public HTTPS receiver (e.g., ngrok).
Set {{api_key}} to your Trebu API key.
Send sample events from each folder to validate parsing and auth.
\nβ
Live β Currently available in production
π§ͺ WIP β Work in progress, not yet available in production
βοΈ Planned β Designed but not yet scheduled for release
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a new load auction (tender batch) is created and made visible to Trebu.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"load_auction.created\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When all posted loads have been awarded or no further carrier options are available.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"load_auction.options_exhausted\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When the auction opens a load to a specific carrier or assigns it contextually (MVP semantics).
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"load_auction.carrier_assigned\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: β Live
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a load (shipment) is created in Trebu with origin/destination and schedule details.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"load.created\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
Whenever non-breaking updates are made to a load (e.g., time changes).
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"load.updated\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: β Live
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a load (shipment) is created in Trebu with origin/destination and schedule details.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\nDelivery is at-least-once (duplicates are possible).
\nRecommended: treat webhooks as notifications and fetch current state via API, or apply client-side dedupe using a content fingerprint (e.g., SHA256 of {event, aggregate.id, occurred_at, payload}).
Schema
Root envelope:
{ \"event\": \"truck_availability.created\", \"data\": { ... } }\n\nCore fields inside data:
id β unique event id
version β event semantic version
schema_version β JSON schema structure version (MVP: 1)
occurred_at β RFC 3339 timestamp
aggregate β primary entity for ordering and context
related β cross-links to other ids (load, carrier, auction, etc.)
payload β event-specific content (see sample body)
Retries & Signatures (MVP)
\nTrebu will retry on non-2xx responses with exponential backoff (configurable in production).
\n(Optional) HMAC signatures may be added in a later version for body integrity.
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a bid request is created for a carrier for a specific load.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"bid_request.created\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a carrier asks the shipper a question about a bid request.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"bid_request.question_asked\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a carrier proposes a rate for a bid request.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"bid_request.rate_proposed\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Pricing fields
\npayload.currency β ISO currency code (e.g., MXN).payload.rate β Monetary amount as string.payload.rate_type β Kind of rate quoted. Allowed: all_in (default), linehaul_only, fuel_inclusive, other.Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When the carriers accepts to do a load or indicates availability to move the load.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\nDelivery is at-least-once (duplicates are possible).
\nRecommended: treat webhooks as notifications and fetch current state via API, or apply client-side dedupe using a content fingerprint (e.g., SHA256 of {event, aggregate.id, occurred_at, payload}).
Schema
Root envelope:
{ \"event\": \"bid_request.accepted\", \"data\": { ... } }\n\nCore fields inside data:
id β unique event id
version β event semantic version
schema_version β JSON schema structure version (MVP: 1)
occurred_at β RFC 3339 timestamp
aggregate β primary entity for ordering and context
related β cross-links to other ids (load, carrier, auction, etc.)
payload β event-specific content (see sample body)
Retries & Signatures (MVP)
\nTrebu will retry on non-2xx responses with exponential backoff (configurable in production).
\n(Optional) HMAC signatures may be added in a later version for body integrity.
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When a load that has been accepted by the carrier is confirmed and assigned to said carrier.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\nDelivery is at-least-once (duplicates are possible).
\nRecommended: treat webhooks as notifications and fetch current state via API, or apply client-side dedupe using a content fingerprint (e.g., SHA256 of {event, aggregate.id, occurred_at, payload}).
Schema
Root envelope:
{ \"event\": \"bid_request.confirmed\", \"data\": { ... } }\n\nCore fields inside data:
id β unique event id
version β event semantic version
schema_version β JSON schema structure version (MVP: 1)
occurred_at β RFC 3339 timestamp
aggregate β primary entity for ordering and context
related β cross-links to other ids (load, carrier, auction, etc.)
payload β event-specific content (see sample body)
Retries & Signatures (MVP)
\nTrebu will retry on non-2xx responses with exponential backoff (configurable in production).
\n(Optional) HMAC signatures may be added in a later version for body integrity.
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Status: π§ͺ WIP
\nPurpose
This webhook informs your system about the following event in the Trebu tendering flow.
When it's sent
When the shipper rejects a carrier's bid request or offer.
Authentication
Include Authorization: Bearer {api_key} in the request headers.
Delivery
\n{event, aggregate.id, occurred_at, payload}).Schema
Root envelope:
{ \"event\": \"bid_request.rejected\", \"data\": { ... } }\nCore fields inside data:
id β unique event idversion β event semantic versionschema_version β JSON schema structure version (MVP: 1)occurred_at β RFC 3339 timestampaggregate β primary entity for ordering and contextrelated β cross-links to other ids (load, carrier, auction, etc.)payload β event-specific content (see sample body)Retries & Signatures (MVP)
\nResponse
Return HTTP 200 as quickly as possible. If you need to do heavy work, enqueue internally and return immediately.
Events Trebu sends to your system. Use these to simulate incoming webhooks to your {{callback_url}}.
Status: π§ͺ WIP
\nPurpose\nSet or replace the single webhook callback URL for your client. All outbound events will be delivered to this URL.
\nSingle URL rule\nEach client can have one active callback URL. Setting a new URL replaces the previous destination immediately.
\nHeaders
\nAuthorization: Bearer {{api_key}}{\n \"callback_url\": \"https://example.com/trebu-hooks\",\n \"updated_at\": \"2025-11-12T17:12:03Z\"\n}\nStatus: π§ͺ WIP
\nReturns the configured webhook callback URL for this client.
\nResponse (200)
\n{\n \"callback_url\": \"https://example.com/trebu-hooks\"\n}\nManage your single callback URL via API.
\n","_postman_id":"1eb7d43e-12ca-400e-8321-8b6fff52397d"},{"name":"Bid Requests","item":[{"name":"π§ͺ [WIP] Reply to carrier question","id":"9494384a-ee66-4adf-8980-0b87bfe7a044","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Api-Key {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"text\": \"Yes, live unload is required.\"\n}"},"url":"https://api.trebu.io/api/v1/bid_requests/{{bid_request_id}}/questions/{{question_id}}/reply","description":"Status: π§ͺ WIP
\nPurpose\nPost an official answer to a question a carrier asked on a bid request.
\nPath params
\nbid_request_idquestion_idBody
\n{\n \"text\": \"Yes, live unload is required.\"\n}\nResult
\nbid_request.question_answered) in a future iteration.Interact with bid requests (e.g., reply to carrier questions).
\n","_postman_id":"20cb920f-5ca5-4bce-b7e9-816a264a5f3a"},{"name":"Loads & Auctions","item":[{"name":"π§ͺ [WIP] Start auction for a load","id":"b513f5e0-5b4e-4fd0-b217-22dda4c9e36a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Api-Key {{api_key}}"}],"body":{"mode":"raw","raw":"{}"},"url":"https://api.trebu.io/api/v1/loads/{{load_id}}/auction-start","description":"Status: π§ͺ WIP
\nPurpose\nCreate and open a load auction using only the load_id path parameter.
Path param
\nload_idBody (optional fields)
\n{\n \"deadline_at\": \"2025-11-12T23:00:00Z\",\n \"timezone\": \"America/Monterrey\",\n \"note\": \"MVP tender for dedicated lane\"\n}\nResponse (201)
\n{\n \"load_auction_id\": \"load_auction_7\",\n \"opened_at\": \"2025-11-11T17:01:00Z\"\n}\nSide effects
\nload_auction.created (and later, carrier_assigned, etc.).Start auctions for specific loads and manage tendering lifecycle.
\n","_postman_id":"5f109e61-210b-46f7-99fa-c1f871f576fd"},{"name":"Facilities","item":[{"name":"β [Live] Add or Update Facility","id":"7b0b6bfe-7722-4528-9785-0a817dc93429","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Api-Key {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"shipper\": \"ACME CORP S.A. de C.V.\",\n \"facility_name\": \"CEDIS ACME Bajio\",\n \"qa_facility_id\": null,\n \"facility_id\": \"6581\",\n \"country\": \"Mexico\",\n \"state\": \"Guanajuato\",\n \"city\": \"LeΓ³n de los Aldama\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.trebu.io/api/v1/update-facilities","urlObject":{"protocol":"https","path":["api","v1","update-facilities"],"host":["api","trebu","io"],"query":[],"variable":[]}},"response":[],"_postman_id":"7b0b6bfe-7722-4528-9785-0a817dc93429"}],"id":"658cfc2b-614d-4c87-b3f7-a184bd8c0008","_postman_id":"658cfc2b-614d-4c87-b3f7-a184bd8c0008","description":""}],"id":"86f2e5cb-9a25-47e1-a64e-c334f8bcee2d","description":"Endpoints you call to interact with Trebu (manage webhooks, reply to questions, start auctions).
\n","_postman_id":"86f2e5cb-9a25-47e1-a64e-c334f8bcee2d"}],"id":"fee4502f-5cd8-4af9-8a43-135bde58ed8e","description":"Current API & Webhooks (MVP). Backwards-compatible additions will land here. Breaking changes will go to v2+.
\n","_postman_id":"fee4502f-5cd8-4af9-8a43-135bde58ed8e"}],"variable":[{"key":"receiver_url","value":"https://example.com/webhooks/trebu"},{"key":"api_key_or_token","value":"REPLACE_ME"}]}