Sinch Webhooks API

openapi: 3.2.0
info:
  title: Sinch Conversation Webhooks API
  description: The Sinch Conversation API is an omnichannel messaging platform that enables developers to send and receive messages across multiple channels including SMS, RCS, WhatsApp, Facebook Messenger, Instagram, Viber, Telegram, KakaoTalk, and LINE through a single unified API. It provides contact management, conversation tracking, message templating, and webhook callbacks for real-time event handling. The API normalizes message formats across channels, allowing developers to build multichannel messaging experiences without channel-specific integrations.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://us.conversation.api.sinch.com
  description: US Production Server
- url: https://eu.conversation.api.sinch.com
  description: EU Production Server
- url: https://br.conversation.api.sinch.com
  description: Brazil Production Server
security:
- oAuth2: []
- basicAuth: []
tags:
- name: Webhooks
  description: Manage webhook endpoints for receiving callbacks on message delivery, inbound messages, and other events.
paths:
  /v1/projects/{project_id}/apps/{app_id}/webhooks:
    get:
      operationId: listWebhooks
      summary: List Webhooks
      description: Returns the list of webhooks configured for a specific app. Up to 5 webhooks can be configured per app.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          description: Unauthorized
    post:
      operationId: createWebhook
      summary: Create a Webhook
      description: Creates a new webhook for the specified app with trigger subscriptions.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/webhooks/{webhook_id}:
    get:
      operationId: getWebhook
      summary: Get a Webhook
      description: Returns the details of a specific webhook.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: webhook_id
        in: path
        required: true
        description: The unique webhook identifier
        schema:
          type: string
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    patch:
      operationId: updateWebhook
      summary: Update a Webhook
      description: Updates the properties of a specific webhook.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: webhook_id
        in: path
        required: true
        description: The unique webhook identifier
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    delete:
      operationId: deleteWebhook
      summary: Delete a Webhook
      description: Deletes a specific webhook.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: webhook_id
        in: path
        required: true
        description: The unique webhook identifier
        schema:
          type: string
      responses:
        '200':
          description: Webhook deleted
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
components:
  schemas:
    CreateWebhookRequest:
      type: object
      required:
      - app_id
      - target
      - triggers
      properties:
        app_id:
          type: string
          description: The app ID
        target:
          type: string
          format: uri
          description: The webhook target URL
        target_type:
          type: string
          enum:
          - HTTP
          - GRPC
          description: The target type
          default: HTTP
        triggers:
          type: array
          description: Event triggers to subscribe to
          items:
            type: string
        secret:
          type: string
          description: Secret for HMAC validation
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The unique webhook identifier
        app_id:
          type: string
          description: The app this webhook belongs to
        target:
          type: string
          format: uri
          description: The webhook target URL
        target_type:
          type: string
          enum:
          - HTTP
          - GRPC
          description: The target type
        triggers:
          type: array
          description: List of event triggers this webhook subscribes to
          items:
            type: string
            enum:
            - MESSAGE_INBOUND
            - EVENT_INBOUND
            - MESSAGE_DELIVERY
            - MESSAGE_SUBMIT
            - CONTACT_CREATE
            - CONTACT_DELETE
            - CONTACT_MERGE
            - CONTACT_UPDATE
            - CONVERSATION_START
            - CONVERSATION_STOP
            - CONVERSATION_DELETE
            - CAPABILITY
            - OPT_IN
            - OPT_OUT
            - CHANNEL_EVENT
            - CONTACT_IDENTITIES_DUPLICATION
            - UNSUPPORTED
            - RECORD_NOTIFICATION
            - SMART_CONVERSATIONS
        secret:
          type: string
          description: Secret for HMAC signature validation
    UpdateWebhookRequest:
      type: object
      properties:
        target:
          type: string
          format: uri
          description: Updated target URL
        target_type:
          type: string
          description: Updated target type
        triggers:
          type: array
          description: Updated trigger list
          items:
            type: string
        secret:
          type: string
          description: Updated secret
    WebhookList:
      type: object
      properties:
        webhooks:
          type: array
          description: List of webhooks
          items:
            $ref: '#/components/schemas/Webhook'
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    AppId:
      name: app_id
      in: path
      required: true
      description: The unique app identifier
      schema:
        type: string
  securitySchemes:
    oAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow using project key ID and secret.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
      description: Key ID as username and key secret as password.
externalDocs:
  description: Sinch Conversation API Documentation
  url: https://developers.sinch.com/docs/conversation