openapi: 3.2.0 info: version: 1.2.1 title: Emerge Public Webhooks API description: 'The Emerge public API provides partner developers with access to core capabilities of the Emerge platform. The current version of the API is v1.2.1. This API will evolve as the features in Emerge''s product evolve. # Get Started The Emerge API is a ''restish'' API and is designed to allow you to work with objects using familiar HTTP verbs like * POST * PUT * DELETE * GET All production level API requests are made to:
`https://api.emergemarket.io` The testing sandbox is available during development and for testing:
`https://demo-api.emergemarket.dev/` ## Compatibility Policy Emerge APIs are versioned using a prefix in the endpoint URL. Within an API version, we only make backward-compatible changes. This mean that when a provider integrates with our REST API, the API will continue to work until the version is deprecated. If we have to create a change that is not compatible with the current version, a new version will be created. ### Non-Breaking Changes * Adding additional optional fields on the API request. * Adding additional fields on the API response. * Adding an HTTP method to an API. * Adding optional headers. * Adding additional accepted enumerated values. * Changing Error Response descriptions. * Added Rate Limits. ### Breaking Changes * Removing or renaming an API method or endpoint. * Removing or renaming existing API request or response fields. * Removing or renaming enumerated values. * Changing the Error Response values. ### Deprecation Policy * Emerge will continue to support deprecated APIs for 1 year. * Documentation will also be updated and integrating providers will be notified via email when a version or endpoint is being deprecated. # Workflows The Emerge API is designed to support two primary workflows for a shipper organization: An opportunity-to-tender workflow and an opportunity-to-award workflow. ## Opportunity-to-tender The opportunity-to-tender is the most common workflow of an integrating system. In this workflow, the Emerge system is used to source the live capacity as well as to tender through Emerge to that live capacity. The benefit of this workflow is that all information, from opportunity through tender and finally tracking is maintained in the Emerge system. The basic steps of this workflow include: 1. Create an Opportunity. 2. Post to the shipper''s (your) marketplace. 3. Receive options from carriers. Retrieval is achieved through a webhook published by you for receiving option events. 4. Tender to a carrier. 5. Get tracking updates through webhook. ## Opportunity-to-award The opportunity-to-award workflow supports customers who are using the Emerge platform in conjunction with their TMS. In this workflow, Emerge is used as a capacity provider while the TMS is used on the execution side. The basic steps of this workflow include: 1. Create an opportunity. 2. Post to the shipper''s (your) marketplace. 3. Receive options from carriers. Retrieval is achieved through a webhook published by you for receiving option events. 4. Award to a carrier. Note that awarding to the carrier will automatically close the opportunity, notify the carrier that they "won" the bidding and notify the remaining carriers that they did not win the bidding. The opportunity-to-award workflow requires that the customer''s TMS tenders to the winning carrier. This happens outside of the Emerge system. ' servers: - url: https://api.emergemarket.io/v1 description: Primary production endpoint - url: https://demo-api.emergemarket.dev/v1 description: Testing sandbox endpoint tags: - name: Webhooks description: "Webhooks are used to provide updates to the TMS when award or option events are generated within the Emerge system.\n

If our webhook message cannot be accepted by the webhook endpoint due to network failures, server errors, or request timeouts we will attempt delivering the message again. We will retry sending the message 6 times with varying gaps of time. \nSee table below:\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Retry CountTime
11 second from initial attempt
24 seconds from first attempt
39 seconds from second attempt
416 seconds from third attempt
525 seconds from fourth attempt
636 seconds from fifth attempt
\t\t\n" paths: /webhooks: description: Webhooks are used to provide updates to the TMS when award or option events are generated within the Emerge system. post: parameters: - name: organization-id in: header description: The Organization GUID for the request. This Emerge provided value is only required if your integration user is in multiple organizations. Note that if multiple headers are passed, the organization from the first instance of the header will be used. example: - 070C895C-AE61-4629-A603-829FC54CD816 required: false schema: type: string tags: - Webhooks summary: Create a new webhook. security: - BearerAuth: [] requestBody: description: Structure of the call to create the webhooks required: true content: application/json: schema: $ref: '#/components/schemas/webhooks' responses: '201': description: 201 | Success. A new webhook has been created and a webhook object is returned content: application/json: schema: $ref: '#/components/schemas/201_createwebhook_response' '400': description: 400 | Bad Request. A bad request was made. Please try again content: application/json: schema: $ref: '#/components/schemas/400_badrequest_webhook_response' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' get: parameters: - name: organization-id in: header description: The Organization GUID for the request. This Emerge provided value is only required if your integration user is in multiple organizations. Note that if multiple headers are passed, the organization from the first instance of the header will be used. example: - 070C895C-AE61-4629-A603-829FC54CD816 required: false schema: type: string tags: - Webhooks summary: Get a list of all webhooks. security: - BearerAuth: [] responses: '200': description: 200 | OK. List of webhooks for the organization content: application/json: schema: $ref: '#/components/schemas/200_getwebhooks_response' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' /webhooks/{webhook_id}: get: tags: - Webhooks summary: Get the details of a webhook by Id. security: - BearerAuth: [] parameters: - name: organization-id in: header description: The Organization GUID for the request. This Emerge provided value is only required if your integration user is in multiple organizations. Note that if multiple headers are passed, the organization from the first instance of the header will be used. example: - 070C895C-AE61-4629-A603-829FC54CD816 required: false schema: type: string - in: path name: webhook_id schema: type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 required: true description: Identifier of the webhook responses: '200': description: 200 | OK. Webhook details content: application/json: schema: $ref: '#/components/schemas/200_getwebhook_response' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' put: tags: - Webhooks summary: Update an existing webhook. security: - BearerAuth: [] parameters: - name: organization-id in: header description: The Organization GUID for the request. This Emerge provided value is only required if your integration user is in multiple organizations. Note that if multiple headers are passed, the organization from the first instance of the header will be used. example: - 070C895C-AE61-4629-A603-829FC54CD816 required: false schema: type: string - in: path name: webhook_id schema: type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 required: true description: Identifier of the webhook requestBody: description: Structure of the call to update the webhook required: true content: application/json: schema: $ref: '#/components/schemas/updatewebhook' responses: '200': description: 200 | OK. The webhook has been updated content: application/json: schema: $ref: '#/components/schemas/errorcode_zero_without_message_object' '400': description: 400 | Bad Request. A bad request was made. Please try again content: application/json: schema: $ref: '#/components/schemas/400_badrequest_webhook_response' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' delete: tags: - Webhooks summary: Delete a webhook. security: - BearerAuth: [] parameters: - name: organization-id in: header description: The Organization GUID for the request. This Emerge provided value is only required if your integration user is in multiple organizations. Note that if multiple headers are passed, the organization from the first instance of the header will be used. example: - 070C895C-AE61-4629-A603-829FC54CD816 required: false schema: type: string - in: path name: webhook_id schema: type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 required: true description: Identifier of the webhook responses: '200': description: 200 | OK. The webhook has been deleted content: application/json: schema: $ref: '#/components/schemas/errorcode_zero_without_message_object' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' components: responses: '403': description: 403 | Forbidden content: application/json: schema: $ref: '#/components/schemas/403_forbidden_response' '401': description: 401 | Not Authorized. The request was not authorized. Please add or refresh your authorization token '404': description: 404 | Not Found. The requested resource was not found schemas: webhooks: type: object description: Details of the webhook. required: - url - content_type - event_types properties: authentication: description: Credentials that Emerge system will send using Basic authentication scheme when calling the webhook for the subscribed event(s). type: object properties: is_enabled: description: Authentication user status . type: boolean default: false example: true username: description: Authentication username. type: string example: username password: description: Authentication password. type: string example: password custom_headers: description: An object containing a set of key-value pairs. For each pair defined in this object, a custom HTTP header is sent in the webhook call for the subscribed event(s). The key becomes the header name, while the value is added as the header value. A possible use case for this feature is when the customer expects each webhook call to have a security key for authentication on their end. type: object example: x-api-key: 070C895C-AE61-4629-A603-829FC54CD816 form_data: type: object description: Object to define the form data format when content type is FormData. properties: payload_property_name: description: FormData property name for the payload type: string example: payload payload_type: description: The payload data format when content type is FormData type: string default: JSON enum: - JSON - XML addon_properties: description: A simple JSON object containing a set of key-value pairs. Each of these key-value pairs will be added to the webhook call payload in addition to the event data information. type: object example: process_id: 34809f4d-75b1-431e-a367-bea47e48636c content_type: description: Request content type. type: string enum: - application/json - application/x-www-form-urlencoded event_types: description: Subscribed event types for the webhook. Note that the API allows multiple subscriptions for any given event type(s) without any duplicate subscription checks. Although this flexibility is required by some consumers for handling certain special cases, duplicate subscription is not recommended in general and should be safeguarded against. If a consumer receives duplicate webhook calls for a single event, a duplicate webhook subscribed by mistake could be the root cause. type: array items: $ref: '#/components/schemas/webhook_event_types' is_enabled: description: Flag to control publishing of the events on webhook Url. type: boolean default: false example: true url: description: URL of the webhook as hosted by the consumer (shipper organization). type: string example: webhook_url 200_getwebhook_response: type: object description: 200 | OK. Details of the webhook properties: response: description: Response of the webhook. type: object properties: authentication: description: Credentials that Emerge system will send using Basic authentication scheme when calling the webhook for the subscribed event(s). type: object properties: is_enabled: description: Authentication user status . type: boolean example: true username: description: Authentication username. type: string example: username password: description: Authentication password. type: string example: password custom_headers: description: An object containing a set of key-value pairs. For each pair defined in this object, a custom HTTP header is sent in the webhook call for the subscribed event(s). The key becomes the header name, while the value is added as the header value. A possible use case for this feature is when the customer expects each webhook call to have a security key for authentication on their end. type: object example: x-api-key: 070C895C-AE61-4629-A603-829FC54CD816 form_data: type: object description: Object to define the form data format when content type is FormData. properties: payload_property_name: description: FormData property name for the payload type: string example: payload payload_type: description: The payload data format when content type is FormData type: string default: JSON enum: - JSON - XML addon_properties: description: A simple JSON object containing a set of key-value pairs. Each of these key-value pairs will be added to the webhook call payload in addition to the event data information. type: object example: process_id: 34809f4d-75b1-431e-a367-bea47e48636c content_type: description: Request content type. type: string enum: - application/json - application/x-www-form-urlencoded event_types: description: Subscribed event types for the webhook. Note that the API allows multiple subscriptions for any given event type(s) without any duplicate subscription checks. Although this flexibility is required by some consumers for handling certain special cases, duplicate subscription is not recommended in general and should be safeguarded against. If a consumer receives duplicate webhook calls for a single event, a duplicate webhook subscribed by mistake could be the root cause. type: array items: $ref: '#/components/schemas/webhook_event_types' id: description: Guid of the webhook. type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 is_enabled: description: Status of the webhook. type: boolean example: true url: description: URL of the webhook as hosted by the consumer (shipper organization). type: string example: webhook_url created_date: description: Created date of the webhook. type: string example: '2019-02-12T02:36:54.2973188+00:00' modified_date: description: Modified date of the webhook. type: string example: '2019-02-12T02:36:54.2973188+00:00' error: $ref: '#/components/schemas/errorcode_zero' 403_forbidden_response: type: object properties: error: type: object properties: code: description: HTTP code type: integer example: 403 messages: description: Error messages type: array items: type: string example: Response status code does not indicate success 403 (Forbidden) updatewebhook: type: object description: Details of the webhook. required: - id - content_type - event_types - url properties: authentication: description: Credentials that Emerge system will send using Basic authentication scheme when calling the webhook for the subscribed event(s). type: object properties: is_enabled: description: Authentication user status . type: boolean example: true username: description: Basic authentication username. type: string example: username password: description: Basic authentication password. type: string example: password custom_headers: description: An object containing a set of key-value pairs. For each pair defined in this object, a custom HTTP header is sent in the webhook call for the subscribed event(s). The key becomes the header name, while the value is added as the header value. A possible use case for this feature is when the customer expects each webhook call to have a security key for authentication on their end. type: object example: x-api-key: 070C895C-AE61-4629-A603-829FC54CD816 form_data: type: object description: Object to define the form data format when content type is FormData. properties: payload_property_name: description: FormData property name for the payload type: string example: payload payload_type: description: The payload data format when content type is FormData type: string default: JSON enum: - JSON - XML addon_properties: description: A simple JSON object containing a set of key-value pairs. Each of these key-value pairs will be added to the webhook call payload in addition to the event data information. type: object example: process_id: 34809f4d-75b1-431e-a367-bea47e48636c content_type: description: Request content type. type: string enum: - application/json - application/x-www-form-urlencoded event_types: description: Subscribed event types for the webhook. Note that the API allows multiple subscriptions for any given event type(s) without any duplicate subscription checks. Although this flexibility is required by some consumers for handling certain special cases, duplicate subscription is not recommended in general and should be safeguarded against. If a consumer receives duplicate webhook calls for a single event, a duplicate webhook subscribed by mistake could be the root cause. type: array items: $ref: '#/components/schemas/webhook_event_types' is_enabled: description: Flag to control publishing of the events on webhook Url. type: boolean example: true url: description: URL of the webhook as hosted by the consumer (shipper organization). type: string example: webhook_url id: description: Guid of the webhook. type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 200_getwebhooks_response: type: object description: 200 | OK. Details of the webhook properties: response: description: Response of the webhook creation. type: array items: type: object properties: authentication: description: Credentials that Emerge system will send using Basic authentication scheme when calling the webhook for the subscribed event(s) type: object properties: is_enabled: description: Authentication user status . type: boolean example: true username: description: Authentication username. type: string example: username password: description: Authentication password. type: string example: password custom_headers: description: An object containing a set of key-value pairs. For each pair defined in this object, a custom HTTP header is sent in the webhook call for the subscribed event(s). The key becomes the header name, while the value is added as the header value. A possible use case for this feature is when the customer expects each webhook call to have a security key for authentication on their end. type: object example: x-api-key: 070C895C-AE61-4629-A603-829FC54CD816 form_data: type: object description: Object to define the form data format when content type is FormData. properties: payload_property_name: description: FormData property name for the payload type: string example: payload payload_type: description: The payload data format when content type is FormData type: string default: JSON enum: - JSON - XML addon_properties: description: A simple JSON object containing a set of key-value pairs. Each of these key-value pairs will be added to the webhook call payload in addition to the event data information. type: object example: process_id: 34809f4d-75b1-431e-a367-bea47e48636c content_type: description: Request content type. type: string enum: - application/json - application/x-www-form-urlencoded event_types: description: Subscribed event types for the webhook. Note that the API allows multiple subscriptions for any given event type(s) without any duplicate subscription checks. Although this flexibility is required by some consumers for handling certain special cases, duplicate subscription is not recommended in general and should be safeguarded against. If a consumer receives duplicate webhook calls for a single event, a duplicate webhook subscribed by mistake could be the root cause. type: array items: $ref: '#/components/schemas/webhook_event_types' id: description: guid of the webhook. type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 is_enabled: description: Status of the webhook. type: boolean example: true url: description: URL of the webhook as hosted by the consumer (shipper organization). type: string example: webhook_url created_date: description: Created date of the webhook. type: string example: '2019-02-12T02:36:54.2973188+00:00' modified_date: description: Modified date of the webhook. type: string example: '2019-02-12T02:36:54.2973188+00:00' error: $ref: '#/components/schemas/errorcode_zero' errorcode_zero_without_message_object: type: object properties: error: type: object properties: code: description: HTTP code type: integer example: 0 201_createwebhook_response: type: object description: 201 | Success. Details of the webhook properties: response: description: Response of the webhook creation. type: object properties: authentication: description: Credentials that Emerge system will send using Basic authentication scheme when calling the webhook for the subscribed event(s) type: object properties: is_enabled: description: Authentication user status . type: boolean example: true username: description: Authentication username. type: string example: username password: description: Authentication password. type: string example: password custom_headers: description: An object containing a set of key-value pairs. For each pair defined in this object, a custom HTTP header is sent in the webhook call for the subscribed event(s). The key becomes the header name, while the value is added as the header value. A possible use case for this feature is when the customer expects each webhook call to have a security key for authentication on their end. type: object example: x-api-key: 070C895C-AE61-4629-A603-829FC54CD816 form_data: type: object description: Object to define the form data format when content type is FormData. properties: payload_property_name: description: FormData property name for the payload type: string example: payload payload_type: description: The payload data format when content type is FormData type: string default: JSON enum: - JSON - XML addon_properties: description: A simple JSON object containing a set of key-value pairs. Each of these key-value pairs will be added to the webhook call payload in addition to the event data information. type: object example: process_id: 34809f4d-75b1-431e-a367-bea47e48636c content_type: description: Request content type. type: string enum: - application/json - application/x-www-form-urlencoded event_types: description: Subscribed event types for the webhook. Note that the API allows multiple subscriptions for any given event type(s) without any duplicate subscription checks. Although this flexibility is required by some consumers for handling certain special cases, duplicate subscription is not recommended in general and should be safeguarded against. If a consumer receives duplicate webhook calls for a single event, a duplicate webhook subscribed by mistake could be the root cause. type: array items: $ref: '#/components/schemas/webhook_event_types' id: description: Guid of the webhook. type: string example: 2bc9eec8-0a66-4e0f-9103-ff4f6ad4ae68 is_enabled: description: Status of the webhook. type: boolean example: true url: description: URL of the webhook as hosted by the consumer (shipper organization). type: string example: webhook_url created_date: description: Created date of the webhook. type: string example: '2019-02-12T02:36:54.2973188+00:00' modified_date: description: Modified date of the webhook. type: string example: '2019-02-12T02:36:54.2973188+00:00' error: $ref: '#/components/schemas/errorcode_zero' errorcode_zero: type: object properties: code: description: HTTP code type: integer example: 0 400_badrequest_webhook_response: type: object properties: error: type: object properties: code: description: HTTP code type: integer example: 400 detailed_errors: description: Error messages type: array items: type: object properties: key: type: string example: url value: type: string example: url must not be empty. messages: type: array items: type: string example: Validation failed. webhook_event_types: description: Webhook event types. type: string enum: - '*' - tracking_status_updated - delivery_status_updated - stop_actual_times_updated - current_location_updated_job - current_marketplace_option - opportunity_awarded - options_changed - tender_status_updated - network_partner_updated - network_partner_deleted - opportunity_deleted - opportunity_not_awarded example: tracking_status_updated securitySchemes: BearerAuth: type: http scheme: bearer x-tagGroups: - name: Shipper API tags: - Authentication - Network Partners - Opportunities - Options - Awards - Tenders - Shipments - name: Webhook Subscription API tags: - Webhooks - name: Webhook Events tags: - Tracking Events - Opportunity Awarded Event - Opportunity Deleted Event - Opportunity Not Awarded Event - Options Changed Event - Tender Status Updated Event - Network Partner Updated Event - Network Partner Deleted Event - Current Marketplace Option Event