akadmin/chatwoot
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix(openapi): document webhook secret in API schema (#14199)

Browse Source 
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 <sdmhbilal@users.noreply.github.com>
Co-authored-by: Sojan Jose <sojan@pepalo.com>
This commit is contained in:
Syed Muhammad Bilal
2026-05-22 16:10:17 +05:30
committed by GitHub
co-authored by Syed Muhammad Bilal Sojan Jose
parent e5d66020fd
commit b9757447a8
7 changed files with 64 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
swagger/definitions/request/webhooks/create_update_payload.yml
+2
View File
@@ -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:
swagger/definitions/resource/webhook.yml
+7 -1
View File
@@ -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
swagger/swagger.json
+11 -2
View File
@@ -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.",
swagger/tag_groups/application_swagger.json
+11 -2
View File
@@ -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.",
swagger/tag_groups/client_swagger.json
+11 -2
View File
@@ -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.",
swagger/tag_groups/other_swagger.json
+11 -2
View File
@@ -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.",
swagger/tag_groups/platform_swagger.json
+11 -2
View File
@@ -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.",