The PushServiceConfigRequest API serves as the configuration gateway for establishing real-time webhook notifications between external systems and the MBE tracking ecosystem. This endpoint functions as an instrumental setup call that configures MBE notification infrastructure, enabling automatic push notifications for shipment status changes without requiring continuous polling by external systems.
In detail, the process is twofold:
Configuration phase: done the through the PushServiceConfigRequest, is a one-time (or periodic) configuration calls to establish webhook endpoints and their credentials. In this way, both endpoint and credentials gets stored and linked for the MOL user.
The data will be stored on MBE systems and linked to the MOL user who made the call. In case of endpoint and/or API Key changes, this call can be done again and the existing data will be overwritten
Operational phase (MBE-initiated webhooks): after the data are correctly sent and stored, MBE systems autonomously perform shipment status monitoring. As soon as a shipment update is intercepted by MBE systems, an automatic webhook delivery is triggered, and the third party is notified about the status change
For the PushServiceConfigRequest, the essential fields are:
TrackingEndpoint: must be a valid accessible HTTPS URL
Apikey: alphanumeric string, is the authentication credential for webhook requests. Will be use by MBE systems to successfully perform the webhook request
Source: strongly recommended, here the source can be stated in order to provide additional classification or routing information
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.onlinembe.eu/ws/">
<soapenv:Header/>
<soapenv:Body>
<ws:PushServiceConfigRequest>
<RequestContainer>
<System></System>
<Credentials>
<Username></Username>
<Passphrase></Passphrase>
</Credentials>
<InternalReferenceid>dafsadsf</InternalReferenceid>
<TrackingEndpoint>https://website/mbewebhook</TrackingEndpoint>
<Apikey>DJDSF484RN2RI329JIR22</Apikey>
<Source>Integrated Third Party Merchant</Source>
</RequestContainer>
</ws:PushServiceConfigRequest>
</soapenv:Body>
</soapenv:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:PushServiceConfigRequestResponse xmlns:ns3="http://www.onlinembe.eu/ws/">
<RequestContainer>
<Status>OK</Status>
</RequestContainer>
</ns3:PushServiceConfigRequestResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:PushServiceConfigRequestResponse xmlns:ns3="http://www.onlinembe.eu/ws/">
<RequestContainer>
<Errors>
<Error>
<Id>5</Id>
<ErrorCode>STR_005</ErrorCode>
<Description>Please provide at least one Apikey</Description>
</Error>
</Errors>
<Status>ERROR</Status>
</RequestContainer>
</ns3:PushServiceConfigRequestResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:PushServiceConfigRequestResponse xmlns:ns3="http://www.onlinembe.eu/ws/">
<RequestContainer>
<Errors>
<Error>
<Id>5</Id>
<ErrorCode>STR_005</ErrorCode>
<Description>Please provide the endpoint</Description>
</Error>
</Errors>
<Status>ERROR</Status>
</RequestContainer>
</ns3:PushServiceConfigRequestResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
JSON Payload elements
Since endpoint and API Key are stored on MBE systems and linked to the MOL user, as soon as HUB intercepts a shipment status update, it will send toward the endpoint a JSON containing the shipment updates.
The JSON payload is as follows:
molUser: MOL user identifier
mbeTrackingNumber
courier: courier service provider
courierTrackingNumber: courier-specific tracking number format
mbeStatus: standardized MBE status code
mbeStatusDescription: description of the MBE status code
1) Delivered
2) Not Delivered
3) In Transit
4) Exception
5) Delivered to sender
6) In transit to sender
courierStatus: original courier status
courierStatusDescription: original courier status description
updatedAt: timestamp of status update (YYYY-MM-DDTHH:mm:ss)
trackingDate
signature
(
[0] => Array
(
[molUser] => moluser.it0001
[mbeTrackingNumber] => IT0001-0L-0000003CJD-01
[courier] => SDA
[courierTrackingNumber] => 2810535267254
[mbeStatus] => 5
[mbeStatusDescription] => Delivered to sender
[courierStatus] => Delivered to sender
[courierStatusDescription] => Delivered to sender
[updatedAt] => 2025-01-29T10:38:57
[trackingDate] => 1736757035000
[signature] => Nicolo
)
)
Note: Call used also by eShip Plugins