The Agoyu API is organized around REST. Our API has predictable resource-oriented URLs, accepts application/json request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Agoyu API in sandbox mode, which doesn't affect your live data or interact with the production networks. The endpoint you use to send the request determines whether the request is live mode or test mode.

Check the signatures

Agoyu can optionally sign the events it sends to your endpoints by including a signature in each event’s Signature header. This allows you to verify that the events were sent by Agoyu, not by a third party. You can verify signatures either using our official libraries, or manually using your own solution.

Before you can verify signatures, you need to retrieve your endpoint’s secret from your Dashboard’s Events settings. Select an endpoint that you want to obtain the secret for, then click the eyes in Signature Key text box to show it.

Agoyu generates a unique key for each endpoint. If you use the same endpoint for both test and live API keys, note that the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on. After this setup, Agoyu starts to sign each event it sends to the endpoint.

To verify the signatures:

• Extract the text of the UTF-8 payload as an array of bytes. The entire body of the HTTP request is used, including line endings.
• Compute a SHA256 HMAC digest for the array of bytes. If your implementation has multiple HMAC keys, compute one digest for each of the HMAC keys configured for your account.
  Base64-encode each of the digests.
• Compare the base64 digest(s) to the values of the x-docusign-signature headers. There will be Signature header value for each HMAC key configured for your account. Compare the one you computed using your application’s key(s). If there is no match, then the notification may be compromised and it should not be trusted. Only one match is required.

The code example to demonstrates the process of implementing this message authenticity check.

const computeHashSignature = (secret, payload) => {
  let hmac = crypto.createHmac('sha256', secret)
  hmac.write(payload)
  hmac.end()
  const hmacHashed = hmac.read().toString('base64')
  return hmacHashed
}
const isValidHash = (secret, payload, verify) => { 
  const isValid = computeHashSignature(secret,payload) == verify
  return isValid && crypto.timingSafeEqual(Buffer.from(verify), Buffer.from(computeHashSignature(secret,payload)))
}
app.all('/event/agoyu', async function (req, res) {
  const data = req.body
  const hashedInRequest = req.headers.Signature ? req.headers.Signature : req.headers.signature
  if (!hashedInRequest) {
    return res.status(400).json({
      message: `Event wasn't include a signature.`
    })
  }
  const secretKey = "put your signature key here"
  if (!checkEventHash(secretKey, JSON.stringify(data), hashedInRequest)) {
    return res.status(400).json({
      message: `Agoyu was sent an invalid signature.`
    })
  }
  // process the request...
  return res.json({
    message: `Mover has been received event.`
  })
})

Webhooks allow you to automate custom backend actions in response to the events that happen in a booking flow.

Events Overview

Events are our way of letting you know when something interesting happens. When an event occurs, we will find out the subscribers and broadcast events to them.

If you registered a webhook endpoint to receive that event, we send it to your endpoint as part of a HTTP (POST | PUT | PATH) request.

Prerequisite

• Your mover account is registered and eligible for using Open API.

Register webhook events

• Login to mover portal and navigate to Open API menu on the left sidebar.
• In the Webhook tab, click Add Webhook Endpoint.
• Fill out the required information in the modal.
  • URL: This is the endpoint to which Agoyu will send requests for any booking or quotation events that occur.
  • Version: The payload may have some mirror changes with each update version.
  • Events: Select the events for which you want to receive information from Agoyu.

Sample payload with event booking that webhook will notify to client

{
    "event": "WEBHOOK_EVENT_BOOKING_SEND_A_NEW_MESSAGE_SLUG",
    "booking": {
      "services": {
        "REFERENCE_BOOKING_TYPE_MOVING": {
          "weight": "3323",
          "price": 552
        },
        "REFERENCE_BOOKING_TYPE_VEHICLE_SHIPPING": {
          "price": 442,
          "info": {
              "pickup_day": 3
          },
          "vehicle_details": [
            {
              "id": 799,
              "title": null,
              "booking_id": 113227,
              "booking_vehicle_id": 649,
              "brand": null,
              "image_id": 3410,
              "image_path": "booking/2022/10/moder12.jpeg",
              "model": "K6",
              "modification": false,
              "notes": null,
              "transport_method": null,
              "year": 2022,
              "created_at": null,
              "updated_at": null,
              "make": "Hispano-Suiza",
              "vehicle_size": 46,
              "class": "sedan",
              "series": "Cabriolet",
              "price": 0
            }
          ]
        },
        "REFERENCE_BOOKING_TYPE_AIR_SHIPMENT": {
          "price": 223322,
          "weight": "2000"
        }
      },
      "id": 113227,
      "user_id": 1331,
      "from_street_address": "Central Park, New York, NY, US",
      "from_apartment": null,
      "from_city": "New York",
      "from_state": "NY",
      "from_zip": null,
      "from_elevator_stair_id": 16,
      "to_street_address": "Asheville, NC, US",
      "to_apartment": null,
      "to_city": "Asheville",
      "to_state": "NC",
      "to_zip": "288",
      "to_elevator_stair_id": 16,
      "contact_name": "pendragon",
      "contact_email": "[email protected]",
      "contact_phone": "11233332",
      "mile": "694.00",
      "price": "994.00",
      "created_at": "2022-10-24 09:08:31",
      "updated_at": "2022-10-24 09:08:33",
      "status": 80,
      "consumer_note": null,
      "from_country": "US",
      "to_country": "US",
      "is_international": false,
      "from_formatted_address": "Central Park, New York, NY, USA",
      "to_formatted_address": "Asheville, NC, USA",
      "move_date": "2022-10-22"
    },
    "message": {
      "mediaUrl": "https://media.us1.twilio.com/MEad0b2d96b45341ab2233ccde7d9d4c89?Expires=1669002300&Signature=FSI3p3Z-avZYuCUSHnYYIY-ZXy7t6ZxXpQLzBYCKlOoXimyNBel7lFT0W2eLrDimCpCQcshzTXEkGNDVGBpekPkbKwia3FCI3qvVkZJca3uYHN7762d0iCcGUY3SmZtRGVK3mJjmNnBCzSa9lUOfnqhHrvY05ddMSLEbE8VsOAxRDTwno47K1vG6Jdv0pWl6dkNNCVTsaJd8iClwGDLB~h17Y9I5-jK8doxYS3tkcPots42jp0Kck8Ogn9rhTUYsmwlES~beK67UwokMcJyBIrwh-DJ3StPlAiK5I2JnwpczJQ7BDzit7voRKzkv-FxDppinM5XvgPRe3XjrmVyebw__&Key-Pair-Id=APKAJWF6YVTMIIYOF3AA",
      "message": "hello"
    }
  }

Sample payload with event quotation that webhook will notify to client

{
    "event": "WEBHOOK_EVENT_QUOTATION_SEND_A_NEW_MESSAGE_SLUG",
    "quotation": {
      "id": 669,
      "book_temporary_id": 6958,
      "consumer_id": 1331,
      "from_street_address": null,
      "to_street_address": null,
      "move_date": null,
      "weight": null,
      "expired_date": "2022-10-26 08:52:47",
      "status": "QUOTED",
      "created_at": "2022-10-24 08:52:47",
      "updated_at": "2022-10-25 03:51:05",
      "is_lock": false,
      "is_third_party_services": false,
      "packing_type": null,
      "packing": false,
      "unpacking": false
    },
    "booking": {
      "user_id": 1331,
      "created_at": "2022-10-21 08:03:28",
      "updated_at": "2022-10-24 08:52:47",
      "id": 6958,
      "mile": "387.00",
      "weight": null,
      "is_international": true,
      "move_date": "2022-10-22",
      "services": {
        "REFERENCE_BOOKING_TYPE_MOVING": {
          "weight": "3323",
          "price": 552
        },
        "REFERENCE_BOOKING_TYPE_VEHICLE_SHIPPING": {
          "price": 442,
          "vehicle_details": [
            {
              "id": 799,
              "title": null,
              "booking_id": 113227,
              "booking_vehicle_id": 649,
              "brand": null,
              "image_id": 3410,
              "image_path": "booking/2022/10/moder12.jpeg",
              "model": "K6",
              "modification": false,
              "notes": null,
              "transport_method": null,
              "year": 2022,
              "created_at": null,
              "updated_at": null,
              "make": "Hispano-Suiza",
              "vehicle_size": 46,
              "class": "sedan",
              "series": "Cabriolet",
              "price": 0
            }
          ]
        },
        "REFERENCE_BOOKING_TYPE_AIR_SHIPMENT": {
          "price": 223322,
          "weight": "2000"
        }
      }
    },
    "message": {
      "mediaUrl": "https://media.us1.twilio.com/MEad0b2d96b45341ab2233ccde7d9d4c89?Expires=1669002300&Signature=FSI3p3Z-avZYuCUSHnYYIY-ZXy7t6ZxXpQLzBYCKlOoXimyNBel7lFT0W2eLrDimCpCQcshzTXEkGNDVGBpekPkbKwia3FCI3qvVkZJca3uYHN7762d0iCcGUY3SmZtRGVK3mJjmNnBCzSa9lUOfnqhHrvY05ddMSLEbE8VsOAxRDTwno47K1vG6Jdv0pWl6dkNNCVTsaJd8iClwGDLB~h17Y9I5-jK8doxYS3tkcPots42jp0Kck8Ogn9rhTUYsmwlES~beK67UwokMcJyBIrwh-DJ3StPlAiK5I2JnwpczJQ7BDzit7voRKzkv-FxDppinM5XvgPRe3XjrmVyebw__&Key-Pair-Id=APKAJWF6YVTMIIYOF3AA",
      "message": "hello"
    }
  }

Read check the signatures to verify that the events were sent by Agoyu, not by a third party after you already received webhook events.

Consumers are increasingly making decisions about which movers or services to use after conducting a moving booking comparison. The Real-time Rate API is intended to allow individual movers to provide their rate for a booking in order to assist consumers in selecting the best mover.

Using the Real-time Rate API, the mover will receive booking information and immediately calculate the rate to display on the Agoyu website.

We currently have 2 authentication mechanisms: Authentication Code & Authentication JWT

Authentication Code

To see details of how this type of authentication works, you can go here

Authentication JWT

To be able to get the token to attach to the url get service information. We need to config the system to get the token

Authentication URL: This is the url point for the system to get the token

Authentication Method: This is the method when system request API Authentication URL

Authentication Key Get Token: This is the key for the system to get the token when request API Authentication URL

Authentication Body: This is the body when system request API Authentication URL

Authentication Header: This is the headers when system request API URL to get service information

• Note:: field code ${token} will help the system automatically push the token to the API when request.

Example: setup config to get token

An open API, also called public API, is an application programming interface made publicly available to software developers. Open APIs are published on the internet and shared freely, allowing the owner of a network-accessible service to give a universal access to consumers.

Open API use the OAuth 2.0 protocol for authentication and authorization.

To work with the public API, you must first get permission from Agoyu to use this feature. After being granted permission, go to OPEN API page in mover system > App > create a new App.

Login to your mover portal, select Open API on the sidebar menu.

In API tab. Click Create a new App button to create an app for you

In modal add application. Enter the app name to create a new app

Once the user completes the steps to create the app, the user has all the information to use Open API.

In the Permission section of app detail, user can self-authorize their account to use what features

Permissions will be mapped to the api as follows:

View and select service areas

• Moving Setting International Service Area
• Moving Setting International Service Area Update
• Moving Setting Domestic Service Area
• Moving Setting Domestic Service Area Update

View and set moving rates

• Moving Setting International Upload Rate HHE
• Moving Setting International Upload Rate Air Shipment
• Moving Setting International Upload Rate Vehicle
• Moving Setting International List Moving Rate HHE
• Moving Setting International Find Moving Rate HHE by ID
• Moving Setting International Moving Rate HHE
• Moving Setting International List Moving Rate Air Shipment
• Moving Setting International Find Moving Rate Air Shipment by ID
• Moving Setting International Moving Rate Air Shipment
• Moving Setting International List Moving Rate Vehicle
• Moving Setting International Find Moving Rate Vehicle by ID
• Moving Setting International Moving Rate Vehicle
• Moving Setting Domestic List Moving Rate Vehicle
• Moving Setting Domestic Find Moving Rate Vehicle by ID
• Moving Setting Domestic Moving Rate Vehicle

View and define Blackout dates

• Moving Setting International List Blackout Date
• Moving Setting International Create Blackout Date
• Moving Setting International Find Blackout Date By ID
• Moving Setting International Update Blackout Date
• Moving Setting International Delete Blackout Date
• Moving Setting Domestic List Blackout Date
• Moving Setting Domestic Create Blackout Date
• Moving Setting Domestic Find Blackout Date By ID
• Moving Setting Domestic Update Blackout Date
• Moving Setting Domestic Delete Blackout Date

View booking details

• List Booking
• Booking Detail

Make offer for services (Booking)

• Make Offer

Confirm Booking

• Confirm Booking

Chat with consumers (Booking)

• List chat
• Chat with consumer

View quotation details

• List Quotation
• Quotation Detail

Quote for quotation

• Quote Quotation

Chat with consumers (Quotation)

• List chat
• Chat with consumer