> ## Documentation Index > Fetch the complete documentation index at: https://help.treble.ai/llms.txt > Use this file to discover all available pages before exploring further. # Webhook Request Examples > This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/treble-webhooks). Treble will call this webhook for different types of events. You must configure the URL of this webhook in the Treble admin panel. ## OpenAPI ````yaml open-api-files/treble-api-en.json POST /treble-webhooks openapi: 3.0.1 info: title: Treble Poll API description: Documentation for the poll deployment endpoint in Treble version: 1.0.0 servers: - url: https://main.treble.ai description: Main Treble server - url: https://yourdomain.com description: >- Example server for implementing webhooks. This represents YOUR server where you must implement the endpoints that Treble will call. security: [] tags: - name: Webhooks description: >- Endpoints that Treble will call on your server. These are not real endpoints that you can call, but a representation of the webhooks that Treble will invoke in your system. paths: /treble-webhooks: post: tags: - Webhooks summary: Webhook - Treble Events description: >- This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/treble-webhooks). Treble will call this webhook for different types of events. You must configure the URL of this webhook in the Treble admin panel. requestBody: description: >- Event information. The type of event is determined by the 'event_type' field. content: application/json: schema: oneOf: - $ref: '#/components/schemas/HSMStatusUpdateEvent' - $ref: '#/components/schemas/ConversationClosedEvent' - $ref: '#/components/schemas/DeploymentFailureEvent' discriminator: propertyName: event_type mapping: hsm.status: $ref: '#/components/schemas/HSMStatusUpdateEvent' session.close: $ref: '#/components/schemas/ConversationClosedEvent' deployment.failure: $ref: '#/components/schemas/DeploymentFailureEvent' examples: hsm.status: summary: HSM Status Update value: event_type: hsm.status event_id: 5f8d7e6a5f8d7e6a5f8d7e6a timestamp: '2024-09-10T12:34:56.789Z' status: APPROVED name: welcome_message affected_conversation_ids: - 12345 - 67890 - 54321 session.close: summary: Conversation closed value: event_type: session.close event_id: f49e36d5-e0b0-4831-87c3-21c4bff033b2 timestamp: '2024-09-10T14:50:40.145000Z' session: external_id: f49e36d5-e0b0-4831-87c3-21c4bff033b2 closed_at: '2024-09-10T14:50:40.145000Z' user: country_code: '+57' cellphone: '1234567890' company: id: 1 cellphone: '+12056192992' messages: - sender: user type: text text: message: Hello, how are you? created_at: '2024-09-10T14:50:30.145000Z' delivered_at: null read_at: null - sender: company type: text text: message: Hello, how are you?, what's your name? created_at: '2024-09-10T14:50:30.145000Z' delivered_at: '2024-09-10T14:50:31.145000Z' read_at: '2024-09-10T14:50:32.145000Z' user_session_keys: - key: name value: John type: null - key: location value: >- {"latitude": 4.5935443, "longitude": -72.0345404, "address": "Carrera 7 #100-06"} type: location hsm: name: welcome_message text: Hello {{1}}, welcome to our customer service. answers: - message: Thank you for the welcome header: type: image url: https://example.com/logo.jpg footer: Reply to this message to continue buttons: type: actions options: - type: quick_reply message: I need help - type: call_to_action subtype: website url: https://example.com/catalog message: View catalog deployment.failure: summary: Deployment failure value: event_id: f49e36d5-e0b0-4831-87c3-21c4bff033b2 timestamp: '2024-09-10T14:50:44.145000Z' event_type: deployment.failure failure_reason: FAILURE_BY_HUMAN_HANDOVER user: country_code: '+57' cellphone: '3178901234' conversation_id: 1 failed_at: '2024-09-10T14:50:44.145000Z' user_session_keys: - key: name value: John type: null responses: '200': description: Successful response content: application/json: schema: type: object description: >- JSON object with the confirmation of reception. The service must respond in less than 5 seconds. servers: - url: https://{webhookUrl} description: Enter your webhook endpoint URL variables: webhookUrl: default: yourdomain.com description: URL of your server where the webhook will be implemented components: schemas: HSMStatusUpdateEvent: title: hsm.status type: object required: - event_type - event_id - timestamp - status - name - affected_conversation_ids description: >- Event that is triggered when the status of an HSM (Highly Structured Message) changes properties: event_type: type: string enum: - hsm.status description: Type of event, always 'hsm.status' for HSM status updates event_id: type: string description: Unique identifier of the event timestamp: type: string format: date-time description: Timestamp of the event in ISO 8601 format status: type: string enum: - APPROVED - REJECTED - PAUSED - DISABLED - PENDING_DELETION description: New status of the HSM name: type: string description: Name or identifier of the HSM affected_conversation_ids: type: array description: IDs of the conversations affected by the status change items: type: integer description: ID of an affected conversation ConversationClosedEvent: title: session.close type: object required: - event_type - event_id - timestamp - session - user - company - messages - user_session_keys - hsm description: >- Event that is triggered when a conversation between a user and the company is closed properties: event_type: type: string enum: - session.close description: Type of event, always 'session.close' for closed conversations event_id: type: string description: Unique identifier of the event timestamp: type: string format: date-time description: Timestamp of the event in ISO 8601 format session: $ref: '#/components/schemas/Session' description: Information of the closed session user: $ref: '#/components/schemas/UserInfo' description: Information of the user company: $ref: '#/components/schemas/CompanyInfo' description: Information of the company messages: type: array description: Messages exchanged during the conversation items: $ref: '#/components/schemas/Message' user_session_keys: type: array description: User session keys collected during the conversation items: $ref: '#/components/schemas/ExtendedUserSessionKey' hsm: $ref: '#/components/schemas/HSMInfo' nullable: true description: Information of the HSM that started the conversation (if applicable) DeploymentFailureEvent: title: deployment.failure type: object required: - event_type - event_id - timestamp - failure_reason - user - conversation_id - failed_at - user_session_keys description: >- Event that is triggered when a failure occurs in the deployment of a conversation properties: event_type: type: string enum: - deployment.failure description: Type of event, always 'deployment.failure' for deployment failures event_id: type: string description: Unique identifier of the event timestamp: type: string format: date-time description: Timestamp of the event in ISO 8601 format failure_reason: type: string enum: - FAILURE - FAILURE_BY_HUMAN_HANDOVER - REVOKED - INVALID_PHONE - FAILURE_BY_RATE_LIMIT - COMPANY_RATE_LIMIT - FAILURE_BY_TIER_CAPACITY - MISSING_PARAMETER - PARAMETER_MISMATCH - FAILURE_BY_BLOCKED_CONTACT - FAILURE_BY_OPTOUT_CONTACT - INVALID_POLL - CHARACTER_LIMIT_HEADER - CHARACTER_LIMIT_BODY - FAILURE_BY_DISABLED_HSM - FAILURE_BY_SPAM_RATE_LIMIT - FAILURE_BY_EXPERIMENT_NUMBER - FAILURE_BY_UNABLE_TO_CONTACT description: Specific reason for the deployment failure user: $ref: '#/components/schemas/UserInfo' description: Information of the user associated with the deployment conversation_id: type: integer description: ID of the conversation related to the deployment failed_at: type: string format: date-time description: Timestamp when the failure occurred user_session_keys: type: array description: User session keys collected during the conversation items: $ref: '#/components/schemas/ExtendedUserSessionKey' Session: type: object required: - external_id - closed_at properties: external_id: type: string description: Unique external ID of the session closed_at: type: string format: date-time description: Date and time when the conversation was closed UserInfo: type: object required: - country_code - cellphone properties: country_code: type: string description: Country code of the user cellphone: type: string description: User's phone number without the country code CompanyInfo: type: object required: - id - cellphone properties: id: type: integer description: ID of the company in Treble cellphone: type: string description: Company's phone number Message: type: object required: - sender - type - created_at - delivered_at - read_at properties: sender: type: string description: Who sent the message (user or company) enum: - user - company type: type: string description: Type of message enum: - text - hsm - image - video - audio - document - location text: $ref: '#/components/schemas/TextMessage' hsm: $ref: '#/components/schemas/HSMMessage' image: $ref: '#/components/schemas/MediaContent' video: $ref: '#/components/schemas/MediaContent' audio: $ref: '#/components/schemas/MediaContent' document: $ref: '#/components/schemas/MediaContent' location: $ref: '#/components/schemas/LocationContent' created_at: type: string format: date-time description: Date and time when the message was created delivered_at: type: string format: date-time nullable: true description: Date and time when the message was delivered read_at: type: string format: date-time nullable: true description: Date and time when the message was read ExtendedUserSessionKey: type: object required: - key - value properties: key: type: string description: Name of the variable value: type: string description: Value of the variable type: type: string nullable: true description: >- Type of the variable. Can be null or a specific type like 'location'. HSMInfo: type: object required: - name - text - answers - header - footer - buttons properties: name: type: string description: Name or identifier of the HSM text: type: string description: Main text of the HSM answers: type: array description: Possible answers for the HSM items: type: object required: - message properties: message: type: string description: Text of the answer header: oneOf: - $ref: '#/components/schemas/HSMHeaderText' - $ref: '#/components/schemas/HSMHeaderMedia' nullable: true description: Header of the HSM (can be text or multimedia) footer: type: string nullable: true description: Footer of the HSM buttons: type: object required: - type - options properties: type: type: string enum: - actions - otp description: Category of buttons options: type: array description: Options of buttons items: oneOf: - $ref: '#/components/schemas/HSMButtonQuickReply' - $ref: '#/components/schemas/HSMButtonCallToAction' - $ref: '#/components/schemas/HSMButtonOTP' nullable: true description: Buttons of the HSM TextMessage: type: object required: - message properties: message: type: string description: Content of the text message HSMMessage: type: object required: - message properties: message: type: string description: Content of the HSM message MediaContent: type: object required: - url properties: url: type: string description: URL of the multimedia file message: type: string description: Photo or description of the multimedia content LocationContent: type: object required: - latitude - longitude properties: latitude: type: number format: float description: Latitude of the location longitude: type: number format: float description: Longitude of the location HSMHeaderText: type: object required: - type - message properties: type: type: string enum: - text description: Type of header message: type: string description: Text of the header HSMHeaderMedia: type: object required: - type - url properties: type: type: string enum: - image - video - document description: Type of media in the header url: type: string description: URL of the multimedia file in the header HSMButtonQuickReply: type: object required: - type - message properties: type: type: string enum: - quick_reply description: Type of quick reply button message: type: string description: Text of the quick reply button HSMButtonCallToAction: type: object required: - type - message - subtype properties: type: type: string enum: - call_to_action description: Type of call to action button subtype: type: string enum: - website - phone description: Subtype of call to action button url: type: string description: URL of the call to action button if the subtype is website phone: type: string description: Phone number of the call to action button if the subtype is phone HSMButtonOTP: type: object required: - type - message properties: type: type: string enum: - otp description: Type of OTP button message: type: string description: Text of the OTP button ````