Registering Web-Hooks with Envase Connect Data

Envase TMS applications need to register a Web-Hook (a URL where notifications will be sent) in order to receive the results from container traces. The application should register the Web-Hook during initialization to insure results are received once containers are published.

The process of registering the Web-Hook is done through the Envase Connect Data API. It requires a POST request providing information about the hook to be registered. The following sections describe the Web-Hooks you’ll want to register when integrating Envase Trace.

Register Results Web-Hook

You’ll want to register a Web-Hook to be notified when new events for containers happen. As Envase Trace traces the containers, the service will notify of the results. The Web-Hook you register will be invoked for every new container result event.

The following is the request you’ll send to Envase Connect Data to register the Web-Hook:

POST https://events.envaseconeect.cloud/api/webhooks

The request body has the following structure:

{
    "url": "https://your-api.com/some/endpoint",
    "triggers": [
        "TRACE_RESULT"
    ],
    "entityType": "CONTAINER"
}

The body requires to specify a url where the notifications will be sent. It also requires an entityType property describing the events for which entity will trigger the notification, which should be set to CONTAINER.

The triggers property is an array of events for which you want to subscribe. To get results, you’ll add the TRACE_RESULT trigger.

The API will generate an id for your Web-Hook and return it with the response:

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-api.com/some/endpoint",
    "triggers": [
        "TRACE_RESULT",
    ],
    "entityType": "CONTAINER"
}

You should store the id, so you can check the status of the Web-Hook when your services restart.

Register Trace Error Web-Hook

Some times, there will be errors attempting to trace containers. These errors are not per container; instead, all containers in a specific job might fail.

For example, imagine that one of the provider sites or APIs are down. It doesn’t matter which container you try to trace, it will fail because Envase Trace will not be able to reach the provider. In these type of cases, a Trace Error event will be sent to the TMS. You will need to register a Web-Hook for that event.

The mechanics are the same:

POST https://events.envaseconeect.cloud/api/webhooks

The request body has the following structure:

{
    "url": "https://your-api.com/some/endpoint",
    "triggers": [
        "FAILED"
    ],
    "entityType": "TRACE"
}

The response will have the same structure as above with a different id.

Note

You can register the same URL for all your Web-Hooks and then evaluate the event type to properly process the events.

Some examples of problems that may cause (but not limited to) a trace error are:

The provider site or API is not available or times out.
A provider where we scrape their site has made changes that break the scrapes and a fix is provided.
A provider has blocked us from scraping. This has happened in the past; that’s why we favor APIs.
The provider site requires customer credentials and the customer has entered the wrong credentials to log in.

There might be other circumstances where a trace job cannot be processed. The important thing to understand is that all those situation will send an event to the TMS to process the event.

Note

When this problems happen, we also send a notification to Microsoft Teams that the Envase Trace team monitors to take action and resolve problems. If the problem is caused by a change that we can address, we fix those problems as soon as possible to minimize customer impact.

Register ICTSI Web-Hook Of Customer

You’ll want to register a Web-Hook to be notified when new events for customer notification is received from ictsi. As ictsi webhook receives the customer details, the service will notify of the results. The Web-Hook you register will be invoked for every new customer result event.

The following is the request you’ll send to Envase Connect Data to register the Web-Hook:

POST https://events.envaseconeect.cloud/api/webhooks

The request body has the following structure:

{
    "url": "https://your-api.com/some/endpoint",
    "triggers": ["TRACE_RESULT"],
    "eventType": "CUSTOMER",
    "filters": [
        {
        "orgId": "ENVASE",
        "svcId": "ICTSI-INTEGRATION"
        }
    ]
}

The body requires to specify a url where the notifications will be sent. It also requires an entityType property describing the events for which entity will trigger the notification, which should be set to CUSTOMER.

The triggers property is an array of events for which you want to subscribe. To get results, you’ll add the TRACE_RESULT trigger. The filters property should have orgId set to ENVASE and svcId set to ICTSI-INTEGRATION.

The API will generate an id for your Web-Hook and return it with the response:

{
    "id": "893b2713-4679-4c0e-89e3-fab03a872287",
    "url": "https://your-api.com/some/endpoint",
    "triggers": [
        "TRACE_RESULT"
    ],
    "eventType": "CUSTOMER",
    "webhookHeaders": [],
    "filters": [
        {
            "orgId": "ENVASE",
            "svcId": "ICTSI-INTEGRATION"
        }
    ]
}

You should store the id, so you can check the status of the Web-Hook when your services restart.

Register ICTSI Web-Hook Of Appointment

You’ll want to register a Web-Hook to be notified when new events for customer notification is received from ictsi. As ictsi webhook receives the customer details, the service will notify of the results. The Web-Hook you register will be invoked for every new appointment result event.

The following is the request you’ll send to Envase Connect Data to register the Web-Hook:

POST https://events.envaseconeect.cloud/api/webhooks

The request body has the following structure:

{
    "url": "https://your-api.com/some/endpoint",
    "triggers": ["TRACE_RESULT"],
    "eventType": "APPOINTMENT",
    "filters": [
        {
        "orgId": "ENVASE",
        "svcId": "ICTSI-INTEGRATION"
        }
    ]
}

The body requires to specify a url where the notifications will be sent. It also requires an entityType property describing the events for which entity will trigger the notification, which should be set to APPOINTMENT.

The triggers property is an array of events for which you want to subscribe. To get results, you’ll add the TRACE_RESULT trigger. The filters property should have orgId set to ENVASE and svcId set to ICTSI-INTEGRATION.

The API will generate an id for your Web-Hook and return it with the response:

{
    "id": "893b2713-4679-4c0e-89e3-fab03a872287",
    "url": "https://your-api.com/some/endpoint",
    "triggers": [
        "TRACE_RESULT"
    ],
    "eventType": "APPOINTMENT",
    "webhookHeaders": [],
    "filters": [
        {
            "orgId": "ENVASE",
            "svcId": "ICTSI-INTEGRATION"
        }
    ]
}

You should store the id, so you can check the status of the Web-Hook when your services restart.

Notification Result Of ICTSI Web-Hook for Appointment

Client applications will be notified of the appointment results through the Envase Connect Data. The appointment event will provide the information about the status, which has the following structure:

{
        "orgId": "ENVASE",
        "svcId": "ICTSI-INTEGRATION",
        "type": "APPOINTMENT",
        "action": "TRACE_RESULT",
        "payload": {
            "id": "reference-number-provided-by-envase",
            "code": "CANCEL",
            "providerId": "ictsi",
            "referenceKey": "ICTSI/PH/SBITC/14079",
            "appointmentNumber": "499",
            "gateId": "SBITC_GATE",
            "requestedDate": "2023-08-03T10:00:00Z",
            "startDate": "2023-08-03T10:00:00Z",
            "endDate": "2023-08-03T11:59:00Z",
            "truckLicense": "",
            "truckCompanyId": "SBITC",
            "truckCompany": "SBITC",
            "deliveryOrder": "TTEU01",
            "containerNumber": "TTEU0010222",
            "cancelled": "2023-08-04T09:19:22Z",
            "created": "2023-08-03T07:47:49Z",
            "updated": "2023-08-04T09:19:23Z"
        }
}

The payload property contains a JSON object with the results of the trace with the following properties:

Name	Type	Description
id	string	The id provided by envase for internal referencing.
code	string	The status of the appointment.
providerId	string	Provider for this appointment result.
referenceKey	string	The Reference Key for Appointment in ICTSI.
appointmentNumber	string	The Appointment Number.
gateId	string	The id of the facility gate.
requestedDate	string	Date/Time when appointment requested.
startDate	ISO Date/Time	Date/Time when appointment starts.
endDate	ISO Date/Time	Date/Time the appointment end.
truckLicense	string	The License of a Truck.
truckCompanyId	string	The Trucking Company Id.
truckCompany	string	Name of Trucking Company.
deliveryOrder	string	The Deliver Order Number.
containerNumber	string	The Container Number.
cancelled	ISO Date/Time	Date/Time when appointment cancelled.
created	ISO Date/Time	Date/Time when appointment created.
updated	ISO Date/Time	Date/Time when appointment updated.

Note

The status property in the payload can contains these values; CANCEL, CREATED, USED, EXPIRED, USEDLATE, LATE and CLOSED

De-Register Web-Hooks with Envase Connect Data

You would want to unsubscribe notifications from envase connect data on specific events, You can do this by sending a DELETE request to the following endpoint:

POST https://events.envaseconeect.cloud/api/webhooks/<WEBHOOK-ID>

The WEBHOOK-ID is the one you get when you subscribe/register with the Envase Connect Data.