From b9757447a855d92720f7607419dc1eaa98b33fc3 Mon Sep 17 00:00:00 2001 From: Syed Muhammad Bilal <32861875+sdmhbilal@users.noreply.github.com> Date: Fri, 22 May 2026 15:40:17 +0500 Subject: [PATCH] fix(openapi): document webhook secret in API schema (#14199) Fixes #13862 Updates the webhook OpenAPI schema to match the current API behavior for webhook secrets and supported subscription events. ## Why Current source already creates per-webhook secrets, returns `secret` from the account webhook API, and uses that secret to sign outbound webhook requests with `X-Chatwoot-Signature`. The OpenAPI schema was behind that contract: - `components.schemas.webhook` did not include the returned `secret` field. - Webhook subscription enums did not include the typing events that are already available in the dashboard webhook form and handled by `WebhookListener`. ## What this change does - Documents `secret` on the webhook response schema. - Documents the outbound webhook signing headers associated with `secret`: `X-Chatwoot-Timestamp`, `X-Chatwoot-Signature`, and `X-Chatwoot-Delivery`. - Adds `conversation_typing_on` and `conversation_typing_off` to webhook subscription enums. - Regenerates the main and tag-group swagger JSON files. ## Validation - Ran `bundle exec rails swagger:build`. - Ran `bundle exec rspec spec/swagger/openapi_spec.rb`. - Verified generated swagger JSON includes `secret`, `conversation_typing_on`, and `conversation_typing_off` in the webhook schemas. --------- Co-authored-by: Syed Muhammad Bilal Co-authored-by: Sojan Jose --- .../request/webhooks/create_update_payload.yml | 2 ++ swagger/definitions/resource/webhook.yml | 8 +++++++- swagger/swagger.json | 13 +++++++++++-- swagger/tag_groups/application_swagger.json | 13 +++++++++++-- swagger/tag_groups/client_swagger.json | 13 +++++++++++-- swagger/tag_groups/other_swagger.json | 13 +++++++++++-- swagger/tag_groups/platform_swagger.json | 13 +++++++++++-- 7 files changed, 64 insertions(+), 11 deletions(-) diff --git a/swagger/definitions/request/webhooks/create_update_payload.yml b/swagger/definitions/request/webhooks/create_update_payload.yml index 485d532e4..d3ad3560c 100644 --- a/swagger/definitions/request/webhooks/create_update_payload.yml +++ b/swagger/definitions/request/webhooks/create_update_payload.yml @@ -21,6 +21,8 @@ properties: 'contact_created', 'contact_updated', 'webwidget_triggered', + 'conversation_typing_on', + 'conversation_typing_off', ] description: The events you want to subscribe to. example: diff --git a/swagger/definitions/resource/webhook.yml b/swagger/definitions/resource/webhook.yml index da5cb112a..a0184afb9 100644 --- a/swagger/definitions/resource/webhook.yml +++ b/swagger/definitions/resource/webhook.yml @@ -21,9 +21,15 @@ properties: "contact_updated", "message_created", "message_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] description: The list of subscribed events + secret: + type: string + nullable: true + description: Secret used to sign webhook requests. Signed webhook deliveries include `X-Chatwoot-Timestamp` and `X-Chatwoot-Signature`; the signature is `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using this secret. Deliveries also include `X-Chatwoot-Delivery` when a delivery id is available. account_id: type: number description: The id of the account which the webhook object belongs to diff --git a/swagger/swagger.json b/swagger/swagger.json index b8b64b009..859453d89 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -10316,11 +10316,18 @@ "contact_updated", "message_created", "message_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The list of subscribed events" }, + "secret": { + "type": "string", + "nullable": true, + "description": "Secret used to sign webhook requests. Signed webhook deliveries include `X-Chatwoot-Timestamp` and `X-Chatwoot-Signature`; the signature is `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using this secret. Deliveries also include `X-Chatwoot-Delivery` when a delivery id is available." + }, "account_id": { "type": "number", "description": "The id of the account which the webhook object belongs to" @@ -12340,7 +12347,9 @@ "message_updated", "contact_created", "contact_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The events you want to subscribe to.", diff --git a/swagger/tag_groups/application_swagger.json b/swagger/tag_groups/application_swagger.json index 17e015139..3eb055649 100644 --- a/swagger/tag_groups/application_swagger.json +++ b/swagger/tag_groups/application_swagger.json @@ -8823,11 +8823,18 @@ "contact_updated", "message_created", "message_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The list of subscribed events" }, + "secret": { + "type": "string", + "nullable": true, + "description": "Secret used to sign webhook requests. Signed webhook deliveries include `X-Chatwoot-Timestamp` and `X-Chatwoot-Signature`; the signature is `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using this secret. Deliveries also include `X-Chatwoot-Delivery` when a delivery id is available." + }, "account_id": { "type": "number", "description": "The id of the account which the webhook object belongs to" @@ -10847,7 +10854,9 @@ "message_updated", "contact_created", "contact_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The events you want to subscribe to.", diff --git a/swagger/tag_groups/client_swagger.json b/swagger/tag_groups/client_swagger.json index 7bc7227fb..721345716 100644 --- a/swagger/tag_groups/client_swagger.json +++ b/swagger/tag_groups/client_swagger.json @@ -2088,11 +2088,18 @@ "contact_updated", "message_created", "message_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The list of subscribed events" }, + "secret": { + "type": "string", + "nullable": true, + "description": "Secret used to sign webhook requests. Signed webhook deliveries include `X-Chatwoot-Timestamp` and `X-Chatwoot-Signature`; the signature is `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using this secret. Deliveries also include `X-Chatwoot-Delivery` when a delivery id is available." + }, "account_id": { "type": "number", "description": "The id of the account which the webhook object belongs to" @@ -4112,7 +4119,9 @@ "message_updated", "contact_created", "contact_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The events you want to subscribe to.", diff --git a/swagger/tag_groups/other_swagger.json b/swagger/tag_groups/other_swagger.json index 6dbfbdd8e..0a526b38b 100644 --- a/swagger/tag_groups/other_swagger.json +++ b/swagger/tag_groups/other_swagger.json @@ -1503,11 +1503,18 @@ "contact_updated", "message_created", "message_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The list of subscribed events" }, + "secret": { + "type": "string", + "nullable": true, + "description": "Secret used to sign webhook requests. Signed webhook deliveries include `X-Chatwoot-Timestamp` and `X-Chatwoot-Signature`; the signature is `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using this secret. Deliveries also include `X-Chatwoot-Delivery` when a delivery id is available." + }, "account_id": { "type": "number", "description": "The id of the account which the webhook object belongs to" @@ -3527,7 +3534,9 @@ "message_updated", "contact_created", "contact_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The events you want to subscribe to.", diff --git a/swagger/tag_groups/platform_swagger.json b/swagger/tag_groups/platform_swagger.json index 952813f62..0b2a3f398 100644 --- a/swagger/tag_groups/platform_swagger.json +++ b/swagger/tag_groups/platform_swagger.json @@ -2264,11 +2264,18 @@ "contact_updated", "message_created", "message_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The list of subscribed events" }, + "secret": { + "type": "string", + "nullable": true, + "description": "Secret used to sign webhook requests. Signed webhook deliveries include `X-Chatwoot-Timestamp` and `X-Chatwoot-Signature`; the signature is `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using this secret. Deliveries also include `X-Chatwoot-Delivery` when a delivery id is available." + }, "account_id": { "type": "number", "description": "The id of the account which the webhook object belongs to" @@ -4288,7 +4295,9 @@ "message_updated", "contact_created", "contact_updated", - "webwidget_triggered" + "webwidget_triggered", + "conversation_typing_on", + "conversation_typing_off" ] }, "description": "The events you want to subscribe to.",