> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wachat.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook

> Create a new webhook endpoint, or update an existing webhook by passing its id.

Create a webhook endpoint for your Wachat account.

Webhooks can listen to all instances or only one specific `apiInstanceName`.

Supported events:

```txt theme={null}
*
messages.upsert
messages.update
contacts.update
chats.update
qrcode.updated
connection.update
```

```bash theme={null}
curl -X POST "https://app.wachat.net/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/wachat/webhook",
    "instanceName": "t1_mq9r2jov_jakarta_store",
    "events": ["messages.upsert", "connection.update"],
    "enabled": true
  }'
```

To receive events from all instances, omit `instanceName`.

## Delivery Headers

Every webhook delivery includes these headers:

```txt theme={null}
X-Wachat-Event
X-Wachat-Timestamp
X-Wachat-Signature
X-Wachat-Webhook-Id
```

`X-Wachat-Signature` is an HMAC-SHA256 signature of:

```txt theme={null}
timestamp.raw_json_body
```

using your webhook secret.

<Note>
  The webhook URL must use HTTPS. The secret is returned when creating/updating a webhook. Store it securely.
</Note>


## OpenAPI

````yaml POST /webhooks
openapi: 3.0.3
info:
  title: Wachat Enterprise API
  description: >
    Welcome to the official Wachat API reference. Wachat provides
    developer-friendly, ultra-reliable infrastructure to scale your WhatsApp
    communications programmatically.


    Easily deploy automated messaging pipelines, orchestrate interactive
    customer engagement patterns, verify phone numbers instantly, and control
    containerized WhatsApp instances via a secure, production-grade REST
    architecture.
  version: 1.0.0
servers:
  - url: https://app.wachat.net/api/v1
    description: Live Production Gateway
security:
  - bearerAuth: []
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create or Update Webhook
      description: >-
        Create a new webhook endpoint, or update an existing webhook by passing
        its id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                id:
                  type: integer
                  description: Existing webhook id. Include this to update a webhook.
                  example: 12
                name:
                  type: string
                  example: Production webhook
                url:
                  type: string
                  description: HTTPS endpoint that will receive Wachat webhook deliveries.
                  example: https://example.com/wachat/webhook
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - '*'
                      - messages.upsert
                      - messages.update
                      - contacts.update
                      - chats.update
                      - qrcode.updated
                      - connection.update
                  example:
                    - messages.upsert
                    - connection.update
                instanceName:
                  type: string
                  description: >-
                    Optional API instance name. Omit this to receive events for
                    all instances in the account.
                  example: t1_mq9r2jov_jakarta_store
                enabled:
                  type: boolean
                  default: true
                  example: true
                secret:
                  type: string
                  description: >-
                    Optional custom webhook secret. If omitted, Wachat generates
                    one.
                  example: whsec_your_custom_secret
      responses:
        '200':
          description: Webhook updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  webhook:
                    $ref: '#/components/schemas/WebhookSubscription'
        '201':
          description: Webhook created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  webhook:
                    $ref: '#/components/schemas/WebhookSubscription'
        '400':
          description: Invalid payload, unsupported event, or non-HTTPS URL.
        '401':
          description: Missing or invalid API key.
        '403':
          description: Subscription restriction prevented webhook creation.
        '404':
          description: Instance or webhook not found.
components:
  schemas:
    WebhookSubscription:
      type: object
      properties:
        id:
          type: integer
          example: 12
        name:
          type: string
          nullable: true
          example: Production webhook
        url:
          type: string
          example: https://example.com/wachat/webhook
        events:
          type: array
          items:
            type: string
          example:
            - messages.upsert
            - connection.update
        enabled:
          type: boolean
          example: true
        secret:
          type: string
          description: >-
            Masked in list responses. Returned in full when creating or updating
            a webhook.
          example: whsec_••••abcdef
        instance:
          type: object
          nullable: true
          properties:
            instanceName:
              type: string
              example: jakarta_store
            displayName:
              type: string
              example: jakarta_store
            apiInstanceName:
              type: string
              example: t1_mq9r2jov_jakarta_store
            internalName:
              type: string
              example: t1_mq9r2jov_jakarta_store
        createdAt:
          type: string
          format: date-time
          example: '2026-06-13T08:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-06-13T08:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate your integration payloads by injecting your premium secure
        Wachat Account API Private Secret Key inside standard Authorization
        Bearer header vectors.

````