Webhook Events#

Afosto fires webhook events for changes to orders and deliveries. Each event delivers the full entity object at the time of the event inside the data field of the payload envelope.

Event reference#

Name	Type	Required	Description
`ORDER_OPENED`	order	Optional	A new order is created. Payload shape: see [Order events](#order-events).
`ORDER_UPDATED`	order	Optional	An order is updated — status change, items added/removed, address changed, etc. Payload shape: see [Order events](#order-events).
`ORDER_CLOSED`	order	Optional	An order is closed. Payload shape: see [Order events](#order-events).
`IN_TRANSIT`	delivery	Optional	A parcel has been picked up and is in transit. Payload shape: see [Delivery events](#delivery-events).
`DELIVERED`	delivery	Optional	A parcel has been delivered to the recipient. Payload shape: see [Delivery events](#delivery-events).

Order events#

ORDER_OPENED, ORDER_UPDATED, and ORDER_CLOSED all deliver the same payload shape. The data field contains the order as returned by the following query:

query getOrder($id: String!) {
  order(id: $id) {
    id
    number
    progress
    items {
      sku
      gtin
      label
      quantity
      details {
        inventory {
          position
          is_deducted
          progress
        }
      }
    }
    meta_data
    delivery {
      method {
        name
        id
      }
      address {
        given_name
        additional_name
        family_name
        organisation
        address_line_1
        address_line_2
        postal_code
        locality
        country_code
      }
    }
    customer {
      notes
      reference
      contact {
        email
      }
    }
    phone_number {
      number
    }
  }
}

Example payload:

{
  "event": "ORDER_OPENED",
  "entity_type": "order",
  "entity_id": "72fca344-2a6f-4b3e-9c1d-5f8a2e7b0d93",
  "message_id": "3a1b2c4d-5e6f-7890-abcd-ef1234567890",
  "triggered_at": 1714000000000,
  "data": {
    "id": "72fca344-2a6f-4b3e-9c1d-5f8a2e7b0d93",
    "number": 1042,
    "progress": "OPEN",
    "items": [
      { "sku": "BLK-HOODIE-M", "gtin": "8712345678901", "label": "Black Hoodie M", "quantity": 2 }
    ],
    "customer": { "contact": { "email": "jan@example.nl" } }
  }
}

Delivery events#

IN_TRANSIT and DELIVERED both deliver the same payload shape. The data field contains the delivery as returned by the following query:

query getDelivery($id: String!) {
  delivery(id: $id) {
    expected_at
    method {
      name
      description
      instruction
      delivery_during
      is_pickup_point
      is_id_check
      is_neighbour_allowed
      i18n {
        locale
        name
        description
        instruction
      }
    }
    provider_option {
      name
      carrier
      description
    }
    from {
      address {
        address_line_1
        address_line_2
        country_code
        locality
        postal_code
        thoroughfare
        premise_number
        premise_number_suffix
      }
      pickup_point {
        name
        carrier
        address {
          address_line_1
          address_line_2
          country_code
          locality
          postal_code
          thoroughfare
          premise_number
          premise_number_suffix
        }
        openings {
          day_of_week
          windows {
            start
            end
          }
        }
      }
    }
    to {
      address {
        address_line_1
        address_line_2
        country_code
        locality
        postal_code
        thoroughfare
        premise_number
        premise_number_suffix
      }
      pickup_point {
        name
        carrier
        address {
          address_line_1
          address_line_2
          country_code
          locality
          postal_code
          thoroughfare
          premise_number
          premise_number_suffix
        }
        openings {
          day_of_week
          windows {
            start
            end
          }
        }
      }
    }
    parcels {
      id
      status
      track_trace {
        number
        url
      }
      items {
        sku
        gtin
        label
        image
        url
        meta_data
        order {
          id
          number
          metadata
          channel {
            id
            name
            logo
            locale
            links {
              type
              value
            }
            business {
              name
              addressing {
                visiting {
                  address_line_1
                  postal_code
                  locality
                  country_code
                }
              }
              phone_number {
                number
              }
            }
            messaging {
              from {
                email
              }
            }
          }
          customer {
            contact {
              given_name
              additional_name
              family_name
            }
          }
        }
      }
    }
  }
}

Example payload:

{
  "event": "DELIVERED",
  "entity_type": "delivery",
  "entity_id": "5f8a2e7b-0d93-4b3e-9c1d-72fca3442a6f",
  "message_id": "ab12cd34-ef56-7890-1234-abcdef567890",
  "triggered_at": 1714050000000,
  "data": {
    "expected_at": "2024-04-25T10:00:00Z",
    "method": { "name": "PostNL", "is_pickup_point": false },
    "parcels": [
      {
        "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
        "status": "DELIVERED",
        "track_trace": {
          "number": "3SYZBA123456789",
          "url": "https://track.postnl.nl/3SYZBA123456789"
        }
      }
    ]
  }
}

Note:

The data object always reflects the entity state at the time of the event, not at delivery time. If retries occur, the data is the same snapshot from when the event was first triggered.