Update Webhook

What it does

Sets the webhook configuration for an application: the HTTPS URL the Gateway posts events to, the custom headers it attaches to each delivery, and which event types you are subscribed to. The same path also serves a read: send it without a body to get the active configuration back instead — see Get Webhook.

Point the URL at a request-inspection service (for example webhook.site) while you are wiring things up, then switch it to your own endpoint. The change takes effect on the next event, with no redeploy on your side.

Your endpoint must be reachable over HTTPS with a valid certificate and must answer HTTP 200 within 5 seconds. Do the real work asynchronously — see Webhooks.

Endpoint

POST /api/v1/apps/{app_id}/webhook

Headers

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

string

required

Always application/json.

Path parameters

string

required

Application ID. Must belong to the organization (otherwise 404).

Request Body

string

required

The HTTPS endpoint that will receive events. Must be publicly reachable and serve a valid TLS certificate.

object

Custom headers the Gateway attaches to every delivery, as a key → value map. Use it to carry your own shared secret or routing token. Send {} to clear the existing headers.

This is a free-form map, so it is the place to put anything your infrastructure needs (an auth token, a tenant ID, a WAF bypass header). Do not put credentials that you would not want to see stored on the configuration.

object

Event name → boolean map controlling which events are delivered. Events set to false, and events you leave out, are not delivered.

Event types

The five event names accepted inside subscribedEvents:

Event	Delivered when
`messages`	A user sent a message to your WhatsApp number.
`message_status`	Outbound message status changed (sent, delivered, failed).
`read`	A user read your outbound message.
`message_template_status`	A template was approved, rejected, or paused.
`account`	Account or phone number update.

The same list, with the endpoints that use it, is on the Webhook Event reference page. Payload shapes for each event are documented on the Webhooks page.

Response

boolean

true when the configuration was saved.

object

The stored configuration, read back after the write.

Show data

string

UUID of the webhook configuration.

string

The URL now in effect.

object

The custom headers now in effect.

object

The event subscriptions now in effect.

boolean

Whether deliveries are enabled for this configuration.

string

ISO-8601 timestamp of creation.

string

ISO-8601 timestamp of this change.

Examples

POST /api/v1/apps/app_7poyXj8GXuv76e/webhook
Authorization: Bearer sk_...
Content-Type: application/json

{
  "url": "https://webhook.site/89ac1ca8-22cc-42c3-9f07-49a47f8f6a13",
  "headers": {
    "X-Signature-Token": "s3cr3t"
  },
  "subscribedEvents": {
    "messages": true,
    "message_status": true,
    "message_template_status": false,
    "read": true,
    "account": false
  }
}

{
  "data": {
    "id": "bb17a17e-9ce1-4c78-88ac-b48f53d322bc",
    "url": "https://webhook.site/89ac1ca8-22cc-42c3-9f07-49a47f8f6a13",
    "headers": {
      "X-Signature-Token": "s3cr3t"
    },
    "subscribedEvents": {
      "messages": true,
      "message_status": true,
      "message_template_status": false,
      "read": true,
      "account": false
    },
    "isActive": true,
    "createdAt": "2026-08-10T22:45:42.314912Z",
    "updatedAt": "2026-08-20T13:36:56.564277Z"
  },
  "isSuccess": true
}

Demo 2 — move to a production URL

POST /api/v1/apps/app_7poyXj8GXuv76e/webhook
Authorization: Bearer sk_...
Content-Type: application/json

{
  "url": "https://api.acme.com/connexease/webhook",
  "headers": {},
  "subscribedEvents": {
    "messages": true,
    "message_status": true,
    "message_template_status": true,
    "read": true,
    "account": true
  }
}

Sending headers: {} clears the previously stored headers.

Demo 3 — inbound messages only

POST /api/v1/apps/app_7poyXj8GXuv76e/webhook
Authorization: Bearer sk_...
Content-Type: application/json

{
  "url": "https://api.acme.com/connexease/webhook",
  "subscribedEvents": {
    "messages": true,
    "message_status": false,
    "message_template_status": false,
    "read": false,
    "account": false
  }
}

Status, read, template, and account events stop being delivered — the Gateway simply drops them for this app.

Demo 4 — verify the change

GET /api/v1/apps/app_7poyXj8GXuv76e/webhook
Authorization: Bearer sk_...

Returns the configuration you just saved. See Get Webhook.

Demo 5 — error: missing url → 400

POST /api/v1/apps/app_7poyXj8GXuv76e/webhook
Authorization: Bearer sk_...
Content-Type: application/json

{ "subscribedEvents": { "messages": true } }

A missing required field is a malformed request, not a field validation error:

{ "errors": { "code": "REQ_001", "group": "VALIDATION", "description": "Missing required field: url" }, "isSuccess": false }

Demo 6 — error: non-HTTPS url → 422

POST /api/v1/apps/app_7poyXj8GXuv76e/webhook
Authorization: Bearer sk_...
Content-Type: application/json

{ "url": "http://api.acme.com/webhook" }

{
  "errors": {
    "code": "VAL_000",
    "group": "VALIDATION",
    "description": "Validation failed.",
    "fields": {
      "url": { "code": "VAL_002", "description": "Invalid value." }
    }
  },
  "isSuccess": false
}

Errors

object

Error details with code, group, and description; isSuccess is false.

HTTP	Code	Group	When
400	`REQ_001`	`VALIDATION`	Missing required field or invalid JSON.
401	`ORGANIZATION_SECRET_010`	`NOT_FOUND`	Authorization / secret key is missing.
401	`ORGANIZATION_SECRET_011`	`NOT_FOUND`	Secret key is invalid.
404	`APPLICATION_004`	`NOT_FOUND`	`app_id` does not belong to the organization.
422	`VAL_000`	`VALIDATION`	Field validation — invalid URL, unknown event name, wrong value type. Each offending field is listed under `errors.fields`.

Next steps

Get Webhook

Read the configuration currently in effect.

Webhook payloads

Event bodies, retries, and endpoint requirements.

Create API Key

Issue a key for an application.

Authentication

How secret keys work.

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Request Body

Event types

Response

Examples

Errors

Next steps

Get Webhook

Webhook payloads

Create API Key

Authentication

​What it does

​Endpoint

​Headers

​Path parameters

​Request Body

​Event types

​Response

​Examples

​Errors

​Next steps

Get Webhook

Webhook payloads

Create API Key

Authentication

What it does

Endpoint

Headers

Path parameters

Request Body

Event types

Response

Examples

Errors

Next steps