Emerge Webhooks API

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:

    <br />`https://api.emergemarket.io`



    The testing sandbox is available during development and for testing:

    <br />`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</br></br>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<table>\n<tr>\n<th>Retry Count</th>\n<th>Time</th>\n</tr>\n<tr>\n<td>1</td>\n<td>1 second from initial attempt</td>\n</tr>\n<tr>\n<td>2</td>\n<td>4 seconds from first attempt</td>\n</tr>\n<tr>\n<td>3</td>\n<td>9 seconds from second  attempt</td>\n</tr>\n<tr>\n<td>4</td>\n<td>16 seconds from third attempt</td>\n</tr>\n<tr>\n<td>5</td>\n<td>25 seconds from fourth attempt</td>\n</tr>\n<tr>\n<td>6</td>\n<td>36 seconds from fifth attempt</td>\n</tr>\n</table>\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: strin

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emerge/refs/heads/main/openapi/emerge-webhooks-api-openapi.yml