Event Types and Payloads

Learn about the different types of webhook events and their payloads.

Item Creation / Update

Action: Vendor uses endpoint to create or update items.

When updating approved products (including quantity decreases), you will not receive webhook notifications for these updates.

Item with Issues

{
"body": {
    "operation": "invalid_item_upload",
    "data": {
      "vendor_sku": "<vendor_sku>",
      "timestamp": "2025-07-16T19:14:09Z",
      "errors": [
        "consignment_id: XYZ is not valid"
      ],
      "consignment_id": null
    }
  }
}

Successful Creation / Update

"body": {
    "operation": "successful_item_upload",
    "data": {
      "vendor_sku": "<vendor_sku>",
      "timestamp": "2025-07-16T19:20:22Z",
      "errors": [],
      "consignment_id": "<consignment_id>"
    }
  }

Order Creation

Action: A customer completes an order containing an item belonging to the vendor.

{
"body": {
    "operation": "item_purchased",
    "data": {
      "vendor_sku": "<vendor_sku>",
      "timestamp": "2025-07-16T18:53:02Z",
      "sku": "<The RealReal SKU>",
      "pdf_url": "shipping_label.pdf"
    }
  }
}

Address Management

Action: Vendor uses endpoint to create, update or delete virtual inventory addresses.

Address Item Update with Errors

{
 "body": {
    "operation": "address_creation",
    "data": {
      "timestamp": "2025-07-16T19:45:07Z",
      "id": null,
      "errors": [
        "zip_code must be in a valid zip or zip+4 format"
      ]
    }
  }

Address Item Update Success

"body": {
    "operation": "address_creation",
    "data": {
      "timestamp": "2025-07-16T19:45:34Z",
      "id": "<address_id>",
      "errors": []
    }
  }

Address Creation with Errors

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "vendor_address_upsert_response",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "address_creation",
    "data": {
      "errors": ["firstname missing"],
      "id": null,
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Address Creation Success

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "vendor_address_upsert_response",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "address_creation",
    "data": {
      "errors": [],
      "id": 50,
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Address Update with Errors

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "vendor_address_upsert_response",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "address_update",
    "data": {
      "errors": ["firstname is missing"],
      "id": 50
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Address Update Success

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "vendor_address_upsert_response",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "address_update",
    "data": {
      "errors": [],
      "id": 50
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Address Deletion with Errors

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "vendor_address_upsert_response",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "address_deletion",
    "data": {
      "errors": ["Cannot delete address because it is associated with active items."],
      "id": "50"
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Address Deletion Success

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "vendor_address_upsert_response",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "address_deletion",
    "data": {
      "errors": [],
      "id": "50"
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Item Cancelation

Action: The vendor can't fulfill an order and cancels an item.

Canceled with Errors

{
  "type": "notification_event",
  "data": {
    "user_id": 12345,
    "user_slug": "john-doe-123",
    "event_type": "virtual_auth_ship_cancel_items",
    "channels": ["webhook"]
  },
  "properties": {
    "external_user_id": "75",
    "operation": "item_cancelation",
    "data": {
      "errors": ["Can't be canceled"],
      "sku": "ABC12345"
    }
  },
  "meta": {
    "topic": "event.viagent.v1"
  }
}

Canceled Success

{
"body": {
    "operation": "item_cancelation",
    "data": {
      "vendor_sku": "<vendor_sku>",
      "trr_sku": "<The RealReal SKU>",
      "timestamp": "2025-07-16T19:47:43Z",
      "errors": []
    }
  }
}

Item Launched to Site

Action: An item has been launched to TheRealReal site. It is now live and available for purchase.

{
  "body": {
    "operation": "item_launched_to_site",
    "data": {
      "vendor_sku": "<vendor_sku>",
      "timestamp": "2025-07-16T19:14:09Z"
    }
  }
}

Item Returning to Vendor

Action: An item canceled or rejected needs to be returned to the vendor. The team in the warehouse is in the process of shipping the item.

{
  "body": {
    "operation": "item_return",
    "data": {
      "label": "<tracking_link>",
      "vendor_sku": "12345",
      "sku": "ABC1234"
    }
  }
}