Webhook Events#

Afosto fires webhook events for orders, deliveries, shipping labels, picklists and user sessions. Each event delivers a snapshot of the related data inside the data field of the payload envelope. The entity_type and entity_id fields in the envelope tell you which entity the event is about.

Note:

An endpoint only receives the events it is subscribed to. Subscriptions are set up by Afosto: contact Afosto support with the endpoint and the events you want to receive.

Event reference#

The type column shows the entity_type sent in the envelope.

Name	Type	Required	Description
`ORDER_CREATED`	ORDER	Optional	An order is created. The order may still be a concept. Payload shape: see [ORDER_CREATED and ORDER_RELEASED](#order_created-and-order_released).
`ORDER_OPENED`	ORDER	Optional	An order is opened: it moved from `CONCEPT` to `OPEN` and processing starts. Payload shape: see [ORDER_OPENED](#order_opened).
`ORDER_UPDATED`	ORDER	Optional	An order is updated: a status change, items added or removed, an address changed, etc. Payload shape: see [ORDER_UPDATED](#order_updated).
`ORDER_RELEASED`	ORDER	Optional	Items on an order are released for delivery. Payload shape: see [ORDER_CREATED and ORDER_RELEASED](#order_created-and-order_released).
`ORDER_KEYSET_UPDATED`	ORDER	Optional	The tags (key sets) on an order are updated. Payload shape: see [ORDER_KEYSET_UPDATED](#order_keyset_updated).
`ORDER_CLOSED`	ORDER	Optional	An order is closed. Payload shape: see [ORDER_CLOSED](#order_closed).
`DELIVERY_IN_TRANSIT`	DELIVERY	Optional	A delivery has been handed to the carrier and is in transit. Payload shape: see [DELIVERY_IN_TRANSIT](#delivery_in_transit).
`LABEL_CREATED`	LABEL	Optional	A shipping label is created for a parcel. Payload shape: see [LABEL_CREATED](#label_created).
`PICKLIST_ITEM_PICKED`	PICKLIST_ITEM	Optional	An item on a picklist is picked. Payload shape: see [Picklist events](#picklist-events).
`PICKLIST_ITEM_UNPICKED`	PICKLIST_ITEM	Optional	A pick on a picklist item is undone. Payload shape: see [Picklist events](#picklist-events).
`JWT_CREATED`	USER	Optional	A user logs in and a session token is issued. Payload shape: see [User session events](#user-session-events).
`JWT_REVOKED`	USER	Optional	A user logs out and the session token is revoked. Payload shape: see [User session events](#user-session-events).

Note:

There is no separate event for a delivered parcel. IN_TRANSIT and DELIVERED are parcel statuses, not webhook events. Use DELIVERY_IN_TRANSIT to get notified when a delivery ships.

Order events#

Each order event delivers the order in data directly, as returned by the query for that event. The events select different fields, so check the query for every event you handle.

ORDER_CREATED and ORDER_RELEASED#

ORDER_CREATED and ORDER_RELEASED 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_CREATED",
  "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": "CONCEPT",
    "items": [
      { "sku": "BLK-HOODIE-M", "gtin": "8712345678901", "label": "Black Hoodie M", "quantity": 2 }
    ],
    "customer": { "contact": { "email": "jan@example.nl" } }
  }
}

ORDER_OPENED#

The data field contains the order as returned by the following query. The order status is returned as state.

query getOrder($id: String!) {
  order(id: $id) {
    id
    number
    state: status
    channel {
      id
    }
    billing {
      address {
        given_name
        additional_name
        family_name
        organisation
        address_line_1
        address_line_2
        postal_code
        locality
        country_code
      }
    }
    items {
      ids
      sku
      total
      subtotal
      gtin
      label
      quantity
      filters {
        key
        value
      }
      image
    }
    meta_data
    delivery {
      method {
        name
        id
      }
      address {
        given_name
        additional_name
        family_name
        organisation
        thoroughfare
        premise_number
        premise_number_suffix
        address_line_1
        address_line_2
        postal_code
        locality
        country_code
      }
    }
    customer {
      notes
      reference
      contact {
        email
        given_name
        family_name
        additional_name
      }
      organisation {
        name
        coc_number
        administration {
          email
        }
        registration {
          number
          country_code
        }
      }
    }
    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",
    "state": "OPEN",
    "channel": { "id": "5d1c7a2e-8f3b-4c6d-9e0a-1b2c3d4e5f60" },
    "items": [
      {
        "ids": ["b6a1e2c3-4d5f-4a7b-8c9d-0e1f2a3b4c5d", "c7b2f3d4-5e6a-4b8c-9d0e-1f2a3b4c5d6e"],
        "sku": "BLK-HOODIE-M",
        "gtin": "8712345678901",
        "label": "Black Hoodie M",
        "quantity": 2,
        "subtotal": 8264,
        "total": 9999
      }
    ],
    "customer": {
      "contact": { "email": "jan@example.nl", "given_name": "Jan", "family_name": "Jansen" }
    }
  }
}

ORDER_UPDATED#

The data field contains the order as returned by the following query. The order status is returned as state.

query getOrderForWebhook($id: String!) {
  order(id: $id) {
    id
    number
    state: status
    billing {
      address {
        given_name
        additional_name
        family_name
        organisation
        address_line_1
        address_line_2
        postal_code
        locality
        country_code
      }
    }
    acceptance {
      amount_covered
      amount_refunded
    }
    items {
      sku
      total
      subtotal
      gtin
      label
      quantity
      image
      details {
        meta_data
      }
      children {
        sku
        gtin
        label
        quantity
        image
        meta_data
      }
    }
    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
        given_name
        family_name
        additional_name
      }
      organisation {
        name
        coc_number
        administration {
          email
        }
        registration {
          number
          country_code
        }
      }
    }
    phone_number {
      number
    }
    total
  }
}

ORDER_KEYSET_UPDATED#

The data field contains the order, including its tags, as returned by the following query. The order status is returned as state.

query getOrder($id: String!) {
  order(id: $id) {
    id
    number
    state: status
    billing {
      address {
        given_name
        additional_name
        family_name
        organisation
        address_line_1
        address_line_2
        postal_code
        locality
        country_code
      }
    }
    items {
      sku
      details {
        meta_data
      }
      children {
        sku
        gtin
        label
        quantity
        image
        meta_data
      }
    }
    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
        given_name
        family_name
        additional_name
      }
      organisation {
        name
        coc_number
        administration {
          email
        }
        registration {
          number
          country_code
        }
      }
    }
    phone_number {
      number
    }
    tags {
      keys {
        label
        values {
          is_active
          label
        }
      }
    }
  }
}

ORDER_CLOSED#

The data field contains the order, including prices, VAT and fees, as returned by the following query. The order status is returned as state.

query getOrderForWebhook($id: String!) {
  order(id: $id) {
    id
    number
    ordered_at
    state: status
    channel {
      id
      name
      type
    }
    billing {
      address {
        given_name
        additional_name
        family_name
        organisation
        address_line_1
        address_line_2
        postal_code
        locality
        country_code
      }
      payment {
        method {
          id
          code
          name
        }
      }
    }
    acceptance {
      amount_covered
      amount_refunded
    }
    items {
      ids
      sku
      total
      subtotal
      vat {
        rate
        amount
      }
      gtin
      label
      quantity
      image
      details {
        meta_data
      }
      children {
        sku
        gtin
        label
        quantity
        image
        meta_data
      }
    }
    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
        given_name
        family_name
        additional_name
      }
      organisation {
        name
        coc_number
        administration {
          email
        }
        registration {
          number
          country_code
        }
      }
    }
    phone_number {
      number
    }
    fees {
      shipping {
        id
        description
        subtotal
        total
        vat {
          rate
          amount
        }
      }
    }
    total
    total_excluding_vat
    subtotal
    is_including_vat
    is_vat_shifted
    vat {
      rate
      amount
    }
  }
}

Delivery, label and picklist events#

These events combine more than one entity. Their data field is an object with one key per entity (for example delivery and user), each holding the result of its own query. user is the user who performed the action.

DELIVERY_IN_TRANSIT#

entity_id is the delivery ID. The data field contains:

delivery: the delivery as returned by the query below
user: the user who shipped the delivery (id, email, name)

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": "DELIVERY_IN_TRANSIT",
  "entity_type": "DELIVERY",
  "entity_id": "5f8a2e7b-0d93-4b3e-9c1d-72fca3442a6f",
  "message_id": "ab12cd34-ef56-7890-1234-abcdef567890",
  "triggered_at": 1714050000000,
  "data": {
    "delivery": {
      "expected_at": 1714137600000,
      "method": { "name": "PostNL", "is_pickup_point": false },
      "parcels": [
        {
          "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
          "status": "IN_TRANSIT",
          "track_trace": {
            "number": "3SYZBA123456789",
            "url": "https://track.postnl.nl/3SYZBA123456789"
          }
        }
      ]
    },
    "user": {
      "id": "a19c7f3e5d2b4c8a90f1e6d7c4b30258",
      "email": "warehouse@example.nl",
      "name": "Iris de Vries"
    }
  }
}

LABEL_CREATED#

entity_id is the label ID. The data field contains:

parcel: the parcel the label was created for, as returned by the query below
user: the user who created the label (id, email, name)

query labelEvent($id: String!) {
  parcel(id: $id) {
    id
    track_trace {
      number
      url
    }
    items {
      sku
      gtin
      label
      order {
        id
        number
      }
    }
  }
}

Example payload:

{
  "event": "LABEL_CREATED",
  "entity_type": "LABEL",
  "entity_id": "e7b2d3a1-4c5f-4890-a1b2-c3d4e5f60718",
  "message_id": "5b9e1c73-2a44-4d18-b0e6-7c3f1a9d2e80",
  "triggered_at": 1714040000000,
  "data": {
    "parcel": {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "track_trace": {
        "number": "3SYZBA123456789",
        "url": "https://track.postnl.nl/3SYZBA123456789"
      },
      "items": [
        {
          "sku": "BLK-HOODIE-M",
          "gtin": "8712345678901",
          "label": "Black Hoodie M",
          "order": { "id": "72fca344-2a6f-4b3e-9c1d-5f8a2e7b0d93", "number": "1042" }
        }
      ]
    },
    "user": {
      "id": "a19c7f3e5d2b4c8a90f1e6d7c4b30258",
      "email": "warehouse@example.nl",
      "name": "Iris de Vries"
    }
  }
}

Picklist events#

PICKLIST_ITEM_PICKED and PICKLIST_ITEM_UNPICKED deliver the same payload shape. entity_id is the picklist item ID. The data field contains:

order: the order the item belongs to (id, number)
user: the user who picked or unpicked the item (id, email, name)
product: the picked product (sku, label)

Example payload:

{
  "event": "PICKLIST_ITEM_PICKED",
  "entity_type": "PICKLIST_ITEM",
  "entity_id": "7a8b9c0d-1e2f-4304-9516-273849506a7b",
  "message_id": "2f4a6c81-5b37-4d92-a1e0-7c3f9b2d1e40",
  "triggered_at": 1714030000000,
  "data": {
    "order": { "id": "72fca344-2a6f-4b3e-9c1d-5f8a2e7b0d93", "number": "1042" },
    "user": {
      "id": "b72e9f1a4c6d8e0f13a5c7b9e2d40316",
      "email": "picker@example.nl",
      "name": "Sven Bakker"
    },
    "product": { "sku": "BLK-HOODIE-M", "label": "Black Hoodie M" }
  }
}

User session events#

JWT_CREATED (login) and JWT_REVOKED (logout) deliver the same payload shape. entity_id is the user ID. The data field contains the user as returned by the following query:

query loginEvent($userId: String!) {
  user(id: $userId) {
    id
    email
    name
  }
}

Example payload:

{
  "event": "JWT_CREATED",
  "entity_type": "USER",
  "entity_id": "d41f8a9c2b7e4d6f90a3c1e5b8f20147",
  "message_id": "8c3d5e7f-9a1b-4c2d-8e3f-4a5b6c7d8e9f",
  "triggered_at": 1714020000000,
  "data": {
    "id": "d41f8a9c2b7e4d6f90a3c1e5b8f20147",
    "email": "jan@example.nl",
    "name": "Jan Jansen"
  }
}

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.