---
updatedAt: 2026-06-12T16:45:46.000Z
agentTools:
  projectIndex: https://docs.hosttools.com/llms.txt
---

# Webhook Message

This documents the webhook payload that Host Tools will POST to your configured webhook URL when a new post is added to a reservation

**Note: This is not an API endpoint you call.**
This documents the requests that Host Tools sends TO your webhook URL.

## When triggered:
- New message/attachment is added to a reservation posts field
- Messages from either guests or hosts

## Attachments:
Images and videos (Airbnb only) are included in `post.attachments`, with a `type` and `mimeType` for each. The webhook is sent once the files are copied into our storage, so a message with a video can arrive a little later than a text-only one. Each `url` expires after 1 hour.

## Handling the webhook:
1. Your endpoint should respond with HTTP 200 status
2. Process the data asynchronously if needed
3. Respond within 30 seconds


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.30.0",
    "title": "Host Tools API Reference",
    "description": "Host Tools API. Supports two authentication methods:\n- **Legacy auth token**: Pass the `authToken` header with your user token\n- **OAuth 2.0 Bearer token**: Pass `Authorization: Bearer <token>` header (see OAuth endpoints below)\n\nOAuth 2.0 is recommended for new integrations. It supports granular scopes and automatic token refresh.\n",
    "contact": {
      "name": "Tom Krones",
      "email": "support@hosttools.com",
      "url": "https://hosttools.com"
    }
  },
  "servers": [
    {
      "url": "https://app.hosttools.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "OAuth2 Access Token",
        "description": "OAuth 2.0 access token obtained via the authorization code flow"
      },
      "authToken": {
        "type": "apiKey",
        "in": "header",
        "name": "authToken",
        "description": "Legacy user authentication token (UUID)"
      }
    },
    "schemas": {
      "Message": {
        "description": "Message webhook payload",
        "required": [
          "type",
          "document"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "message"
            ],
            "description": "Webhook type"
          },
          "document": {
            "type": "object",
            "description": "Message document",
            "required": [
              "userID",
              "listingID",
              "reservationID",
              "post"
            ],
            "properties": {
              "userID": {
                "type": "string",
                "description": "User ID",
                "example": "5e7a6c0b0f2c9c0017b0b0b0"
              },
              "listingID": {
                "type": "string",
                "description": "Listing ID",
                "example": "5e7a6c0b0f2c9c0017b0b0b0"
              },
              "reservationID": {
                "type": "string",
                "description": "Reservation ID",
                "example": "5e7a6c0b0f2c9c0017b0b0b0"
              },
              "post": {
                "$ref": "#/components/schemas/Post"
              }
            }
          }
        }
      },
      "Post": {
        "description": "A post in a reservation",
        "required": [
          "_id",
          "isGuest",
          "sentTimestamp"
        ],
        "properties": {
          "_id": {
            "type": "string",
            "description": "Post ID",
            "example": "5e7a6c0b0f2c9c0017b0b0b0"
          },
          "message": {
            "type": "string",
            "description": "Message content",
            "example": "Hello, this is a test message"
          },
          "isGuest": {
            "type": "boolean",
            "description": "Whether the message is from a guest",
            "example": true
          },
          "role": {
            "type": "string",
            "description": "Who sent the message",
            "enum": [
              "guest",
              "host",
              "cohost",
              "cleaner",
              "support",
              "unknown"
            ],
            "example": "guest"
          },
          "sentTimestamp": {
            "type": "string",
            "format": "string",
            "description": "When the message was sent in UTC",
            "example": "2022-05-20T00:00:00.000Z"
          },
          "attachments": {
            "type": "array",
            "description": "Message attachments: images, videos or other files.\n\nVideos come from Airbnb guests only, as MP4 or MOV files up to 100 MB. Other channels send images only.",
            "items": {
              "type": "object",
              "required": [
                "url",
                "type"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "Attachment URL, served from Host Tools storage. The link expires after 1 hour and changes on every response, so don't store it or embed it in a UI. Download the file for later use, or call `/api/getReservation/{reservationID}` again for a fresh link.\n\nAn attachment is omitted until it has been copied into our storage, which happens shortly after the message arrives. A video takes longer to copy than an image. Poll again if a very recent message reports no attachments.",
                  "example": "https://example.com/attachment.jpg"
                },
                "type": {
                  "type": "string",
                  "description": "What the attachment is. `file` is anything that's neither an image nor a video, such as a PDF.",
                  "enum": [
                    "image",
                    "video",
                    "file"
                  ],
                  "example": "image"
                },
                "mimeType": {
                  "type": "string",
                  "description": "The file's MIME type, from its extension. Absent when the file has no extension or an unknown one.",
                  "example": "image/jpeg"
                }
              }
            }
          }
        }
      },
      "Success": {
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    },
    {
      "authToken": []
    }
  ],
  "paths": {
    "/webhooks/message": {
      "post": {
        "summary": "Webhook Message",
        "description": "This documents the webhook payload that Host Tools will POST to your configured webhook URL when a new post is added to a reservation\n\n**Note: This is not an API endpoint you call.**\nThis documents the requests that Host Tools sends TO your webhook URL.\n\n## When triggered:\n- New message/attachment is added to a reservation posts field\n- Messages from either guests or hosts\n\n## Attachments:\nImages and videos (Airbnb only) are included in `post.attachments`, with a `type` and `mimeType` for each. The webhook is sent once the files are copied into our storage, so a message with a video can arrive a little later than a text-only one. Each `url` expires after 1 hour.\n\n## Handling the webhook:\n1. Your endpoint should respond with HTTP 200 status\n2. Process the data asynchronously if needed\n3. Respond within 30 seconds\n",
        "tags": [
          "Webhook"
        ],
        "requestBody": {
          "description": "Webhook payload sent by Host Tools",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Message"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook received successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          }
        }
      }
    }
  }
}
```