> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/api-reference/webhook-subscription.md).
# Webhook Subscription
These endpoints will allow you to easily manage webhooks subscriptions.\
\
Our requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response.\
In the case of 4xx or 5xx response codes, we retry sending the webhook once.
## Get webhook subscriptions list
> \\ \ \
> If sorting is not chosen, the rows will be returned in an unspecified order. \
> To sort a result, use an \`\_orderBy\` parameter in query.
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}},"page":{"name":"_page","in":"query","description":"Number of page with results, starts from 1","required":false,"schema":{"type":"integer","default":1,"minimum":1}},"itemsOnPage":{"name":"_itemsOnPage","in":"query","description":"Items on one page","required":false,"schema":{"type":"integer","default":10,"maximum":50,"minimum":1}},"orderBy":{"name":"_orderBy","in":"query","description":"Sorting order. If sorting is not chosen, the rows will be returned in an unspecified order. Sort order: * `asc` - Ascending, from A to Z * `desc` - Descending, from Z to A","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]}}}},"schemas":{"WebhookSubscription":{"properties":{"webhookSubscriptionId":{"type":"string","format":"uuid"},"eventName":{"type":"string"},"url":{"type":"string"},"headerName":{"type":"string","deprecated":true},"headerValue":{"type":"string","deprecated":true},"legacy":{"type":"boolean","deprecated":true},"createdAt":{"type":"string","format":"date-time"},"destinationType":{"type":"string"},"hmacEnabled":{"type":"boolean"},"hmacSecretKeyVersion":{"type":"integer"},"hmacSecretRotatedAt":{"type":"string","format":"date-time"}},"type":"object"},"SearchableTotalResponse2":{"properties":{"all":{"type":"integer","deprecated":true},"filtered":{"type":"integer","deprecated":true},"estimated":{"description":"Field estimated is used to show that the results are estimated. It might happen when there are more than 5000 results due to performance optimization.","type":"boolean","deprecated":true}},"type":"object","deprecated":true},"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}},"responses":{"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}}},"paths":{"/api/{storeCode}/webhook/subscription":{"get":{"tags":["Webhook subscription"],"summary":"Get webhook subscriptions list","description":"
\nIf sorting is not chosen, the rows will be returned in an unspecified order. \nTo sort a result, use an `_orderBy` parameter in query.\n","operationId":"webhookSubscriptionGetList","parameters":[{"$ref":"#/components/parameters/storeCode"},{"name":"url","in":"query","required":false,"schema":{"type":"string"}},{"name":"legacy","in":"query","required":false,"deprecated":true,"schema":{"type":"boolean"}},{"name":"eventName","in":"query","required":false,"schema":{"type":"string"}},{"name":"createdAt","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/itemsOnPage"},{"$ref":"#/components/parameters/orderBy"}],"responses":{"200":{"description":"List of webhook subscriptions","content":{"application/json":{"schema":{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"total":{"$ref":"#/components/schemas/SearchableTotalResponse2"}},"type":"object"}}}},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"}}}}}}
````
## Subscribe to a webhook
> \\ \ \
> This method allows adding a new webhook subscription to the system.\
> When \`hmacEnabled\` is set to \`true\`, the response includes a one-time plaintext HMAC secret key\
> (\`whsec\_\` prefix). The key is never shown again — store it securely.
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}}},"schemas":{"PostRestWebhookSubscriptionRequestBody":{"title":"REST Webhook","properties":{"webhookSubscription":{"required":["eventName","url"],"properties":{"eventName":{"description":"Name of the event to subscribe to (e.g. \"AchievementsWereProcessed\")","type":"string"},"destinationType":{"description":"Type of destination for the webhook","type":"string","enum":["rest"]},"url":{"description":"URL to send the webhook to. HTTPS is required when hmacEnabled is true.","type":"string"},"hmacEnabled":{"description":"Enable HMAC signing for webhook payloads. When true, HTTPS URL is required. A secret key is auto-generated and returned once in the response.","type":"boolean","default":false},"headerName":{"description":"Name of the header (deprecated, use headers instead)","type":"string","deprecated":true},"headerValue":{"description":"Value of the header (deprecated, use headers instead)","type":"string","deprecated":true},"headers":{"description":"Headers to include in the webhook request (for REST destination type)","type":"array","items":{"$ref":"#/components/schemas/WebhookHeader"}}},"type":"object"}},"type":"object"},"WebhookHeader":{"properties":{"headerName":{"description":"Name of the header","type":"string"},"headerValue":{"description":"Value of the header","type":"string"}},"type":"object"},"PostQueueWebhookSubscriptionRequestBody":{"title":"Queue Webhook","properties":{"webhookSubscription":{"required":["eventName","url","queueKey","queueSecretKey"],"properties":{"eventName":{"description":"Name of the event to subscribe to (e.g. \"AchievementsWereProcessed\")","type":"string"},"destinationType":{"description":"Type of destination for the webhook","type":"string","enum":["queue"]},"url":{"description":"URL to send the webhook to","type":"string"},"queueKey":{"description":"Queue Access Key (for QUEUE destination type)","type":"string"},"queueSecretKey":{"description":"Queue Secret Access Key (for QUEUE destination type)","type":"string"},"queueEncryptionKey":{"description":"RSA public key in PEM format for encrypting webhook messages","type":"string","format":"textarea"}},"type":"object"}},"type":"object"},"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}},"responses":{"BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"required":["code","message","errors"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"required":["message","parameters","plural","code","path"],"properties":{"message":{"type":"string"},"parameters":{},"plural":{"type":"integer","nullable":true},"code":{"type":"string"},"path":{"type":"string"}},"type":"object"}}},"type":"object"}}}},"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}}},"paths":{"/api/{storeCode}/webhook/subscription":{"post":{"tags":["Webhook subscription"],"summary":"Subscribe to a webhook","description":"
\nThis method allows adding a new webhook subscription to the system.\nWhen `hmacEnabled` is set to `true`, the response includes a one-time plaintext HMAC secret key\n(`whsec_` prefix). The key is never shown again — store it securely.\n","operationId":"_webhookSubscriptionPost","parameters":[{"$ref":"#/components/parameters/storeCode"}],"requestBody":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PostRestWebhookSubscriptionRequestBody"},{"$ref":"#/components/schemas/PostQueueWebhookSubscriptionRequestBody"}]}}}},"responses":{"200":{"description":"Return created webhook subscription ID. When HMAC is enabled, also returns the one-time plaintext secret key.","content":{"application/json":{"schema":{}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"}}}}}}
````
## Get a webhook subscription details
> \\ \
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}},"webhookSubscription":{"name":"subscription","in":"path","description":"Webhook subscription ID","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"WebhookSubscriptionDetails":{"properties":{"webhookSubscriptionId":{"type":"string","format":"uuid"},"eventName":{"type":"string"},"url":{"type":"string"},"headerName":{"description":"Use 'headers' field instead.","type":"string","deprecated":true},"headerValue":{"description":"Use 'headers' field instead.","type":"string","deprecated":true},"headers":{"type":"array","items":{"$ref":"#/components/schemas/WebhookHeader2"}},"legacy":{"type":"boolean","deprecated":true},"createdAt":{"type":"string","format":"date-time"},"destinationType":{"type":"string"},"hmacEnabled":{"type":"boolean"},"hmacSecretKeyVersion":{"type":"integer"},"hmacSecretRotatedAt":{"type":"string","format":"date-time"}},"type":"object"},"WebhookHeader2":{"properties":{"headerName":{"type":"string"},"headerValue":{"type":"string"}},"type":"object"},"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}},"responses":{"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}},"NotFound":{"description":"Not found.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}}},"paths":{"/api/{storeCode}/webhook/subscription/{webhookSubscription}":{"get":{"tags":["Webhook subscription"],"summary":"Get a webhook subscription details","description":"
\n","operationId":"webhookSubscriptionGet","parameters":[{"$ref":"#/components/parameters/storeCode"},{"$ref":"#/components/parameters/webhookSubscription"},{"name":"webhookSubscription","in":"path","required":true,"schema":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"}}],"responses":{"200":{"description":"Webhook subscription details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionDetails"}}}},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
````
## Update subscription to a webhook
> \\ \ \
> This method allows updating an existing webhook subscription.\
> When \`hmacEnabled\` is set to \`true\` on a subscription that does not already have HMAC,\
> the response includes a one-time plaintext HMAC secret key (\`whsec\_\` prefix).\
> The key is never shown again — store it securely.\
> When \`hmacEnabled\` is omitted, the HMAC state is not changed (backward compatible).
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}}},"schemas":{"PutRestWebhookSubscriptionRequestBody":{"title":"Update REST Webhook","properties":{"webhookSubscription":{"required":["url"],"properties":{"destinationType":{"description":"Type of destination for the webhook","type":"string","enum":["rest"]},"url":{"description":"URL to send the webhook to. HTTPS is required when hmacEnabled is true.","type":"string"},"hmacEnabled":{"description":"Enable or disable HMAC signing. When true, HTTPS URL is required. When omitted, HMAC state is not changed. A secret key is auto-generated and returned once when enabling.","type":"boolean"},"headerName":{"description":"Name of the header (deprecated, use headers instead)","type":"string","deprecated":true},"headerValue":{"description":"Value of the header (deprecated, use headers instead)","type":"string","deprecated":true},"headers":{"description":"Headers to include in the webhook request (for REST destination type)","type":"array","items":{"$ref":"#/components/schemas/WebhookHeader"}}},"type":"object"}},"type":"object"},"WebhookHeader":{"properties":{"headerName":{"description":"Name of the header","type":"string"},"headerValue":{"description":"Value of the header","type":"string"}},"type":"object"},"PutQueueWebhookSubscriptionRequestBody":{"title":"Update Queue Webhook","properties":{"webhookSubscription":{"required":["url","queueKey","queueSecretKey"],"properties":{"destinationType":{"description":"Type of destination for the webhook","type":"string","enum":["queue"]},"url":{"description":"URL to send the webhook to","type":"string"},"queueKey":{"description":"Queue Access Key (for QUEUE destination type)","type":"string"},"queueSecretKey":{"description":"Queue Secret Access Key (for QUEUE destination type)","type":"string"},"queueEncryptionKey":{"description":"RSA public key in PEM format for encrypting webhook messages","type":"string","format":"textarea"}},"type":"object"}},"type":"object"},"PutWebhookSubscriptionHmacEnabledResponse":{"properties":{"hmacSecretKey":{"description":"One-time plaintext HMAC secret key (whsec_ prefix + 64 hex chars). Store securely — this key will never be shown again.","type":"string"},"hmacSecretKeyWarning":{"description":"Warning message about one-time key display.","type":"string"}},"type":"object"},"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}},"responses":{"NoContent":{"description":"Success. No content."},"BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"required":["code","message","errors"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"required":["message","parameters","plural","code","path"],"properties":{"message":{"type":"string"},"parameters":{},"plural":{"type":"integer","nullable":true},"code":{"type":"string"},"path":{"type":"string"}},"type":"object"}}},"type":"object"}}}},"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}},"NotFound":{"description":"Not found.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}}},"paths":{"/api/{storeCode}/webhook/subscription/{webhookSubscription}":{"put":{"tags":["Webhook subscription"],"summary":"Update subscription to a webhook","description":"
\nThis method allows updating an existing webhook subscription.\nWhen `hmacEnabled` is set to `true` on a subscription that does not already have HMAC,\nthe response includes a one-time plaintext HMAC secret key (`whsec_` prefix).\nThe key is never shown again — store it securely.\nWhen `hmacEnabled` is omitted, the HMAC state is not changed (backward compatible).\n","operationId":"_webhookSubscriptionPut","parameters":[{"$ref":"#/components/parameters/storeCode"},{"name":"webhookSubscription","in":"path","description":"Webhook Subscription ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PutRestWebhookSubscriptionRequestBody"},{"$ref":"#/components/schemas/PutQueueWebhookSubscriptionRequestBody"}]}}}},"responses":{"200":{"description":"HMAC was enabled on the subscription. Returns the one-time plaintext secret key. This key will never be shown again.","headers":{"Cache-Control":{"schema":{"type":"string"}},"Pragma":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutWebhookSubscriptionHmacEnabledResponse"}}}},"204":{"$ref":"#/components/responses/NoContent"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
````
## Delete subscription to a webhook
> \\ \
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}},"webhookSubscription":{"name":"subscription","in":"path","description":"Webhook subscription ID","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"NoContent":{"description":"Success. No content."},"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}},"NotFound":{"description":"Not found.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}},"schemas":{"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}}},"paths":{"/api/{storeCode}/webhook/subscription/{webhookSubscription}":{"delete":{"tags":["Webhook subscription"],"summary":"Delete subscription to a webhook","description":"
\n","operationId":"webhookSubscriptionDelete","parameters":[{"$ref":"#/components/parameters/storeCode"},{"$ref":"#/components/parameters/webhookSubscription"},{"name":"webhookSubscription","in":"path","required":true,"schema":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"}}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
````
## Get webhook event types
> \\ \
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}}},"schemas":{"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}},"responses":{"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}}},"paths":{"/api/{storeCode}/webhook/event":{"get":{"tags":["Webhook subscription"],"summary":"Get webhook event types","description":"
\n","operationId":"webhookEventGetList","parameters":[{"$ref":"#/components/parameters/storeCode"}],"responses":{"200":{"description":"List of webhook events","content":{"application/json":{"schema":{"properties":{"items":{"type":"array","items":{"type":"string"}}},"type":"object"}}}},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"}}}}}}
````
## Rotate HMAC secret key
> \\ \ \
> Rotates the HMAC secret key for a webhook subscription. Returns the new plaintext key exactly once.\
> The old key is immediately invalidated. Rate limited to once every 5 minutes.
````json
{"openapi":"3.0.0","info":{"title":"Open Loyalty","version":"0.0.1"},"tags":[{"name":"Webhook subscription","description":"These endpoints will allow you to easily manage webhooks subscriptions.
\nOur requests sent to the endpoint configured in the webhook subscription are synchronous, so we wait for a response. \nIn the case of 4xx or 5xx response codes, we retry sending the webhook once. \n"}],"servers":[{"url":"http://openloyalty.localhost"}],"security":[{"Bearer":[]},{"token":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Open Loyalty has the JWT authorization.\nTo learn what a JSON Web Token is and how it works, check out Introduction to JSON Web Tokens \n\n### Obtain an access token\n\nSend a request with the parameters username and password\n\n#### Definition\n\n`POST /api/admin/login_check` [Go to definition](#operation/adminLoginCheck)\\\n`POST /api/{storeCode}/member/login_check` [Go to definition](#operation/memberLoginCheck)\n\n#### Example\n\n```bash\ncurl {HOST}/api/admin/login_check\n -H 'Content-Type: application/json;charset=UTF-8'\n -H 'Accept: application/json, text/plain, */*'\n --data-binary '{\"username\":\"admin\",\"password\":\"password\"}'\n```\n\n#### Example Response\n\n```json\n{\n \"token\":\"eyJhbGciOiJSUzI1NiIsInR5cCI6...\",\n \"refresh_token\":\"0558f8bb29948c4e54c443f...\"\n}\n```\n\n### Using JSON Web Token\n\nAdd authorization header to each request\\\n`Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...`\\\nYou can now access any API method you want under the /api prefix.\n\n#### Example\n```bash\ncurl {HOST}/api/{storeCode}/analytics/members\n -H 'Accept: application/json'\n -H 'Content-type: application/x-www-form-urlencoded'\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...'\n```\n\n### Refresh JSON Web Token\nYou can refresh token using refresh_token that was given during login.\\\nThere are two endpoints\\\nTo refresh admin token `POST /api/token/refresh` [Go to definition](#operation/tokenRefresh)\\\nTo refresh member token `POST /api/{storeCode}/token/refresh` [Go to definition](#operation/tokenRefreshMember)\n","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"},"token":{"type":"apiKey","name":"X-AUTH-TOKEN","in":"header"}},"parameters":{"storeCode":{"name":"storeCode","in":"path","description":"Store code","required":true,"schema":{"type":"string"}}},"schemas":{"RotateHmacSecretRequestBody":{"properties":{"reason":{"description":"Reason for rotation (default: \"Manual rotation\")","type":"string","maxLength":255}},"type":"object"},"RotateHmacSecretResponse":{"properties":{"message":{"type":"string"},"newSecretKey":{"description":"One-time plaintext HMAC secret key (whsec_ prefix + 64 hex chars). Store securely — this key will never be shown again.","type":"string"},"warning":{"type":"string"}},"type":"object"},"ErrorResponse":{"properties":{"error":{"description":"Error message","type":"string"}},"type":"object"},"ExpiredToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"InvalidToken":{"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Unauthorized":{"required":["message"],"properties":{"message":{"type":"string"}},"type":"object"}},"responses":{"AccessDenied":{"description":"Forbidden.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}},"NotFound":{"description":"Not found.","content":{"application/json":{"schema":{"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}}}}},"paths":{"/api/{storeCode}/webhook/subscription/{webhookSubscriptionId}/rotate-secret":{"post":{"tags":["Webhook subscription"],"summary":"Rotate HMAC secret key","description":"
\nRotates the HMAC secret key for a webhook subscription. Returns the new plaintext key exactly once.\nThe old key is immediately invalidated. Rate limited to once every 5 minutes.\n","operationId":"_webhookSubscriptionRotateHmacSecret","parameters":[{"$ref":"#/components/parameters/storeCode"},{"name":"webhookSubscriptionId","in":"path","description":"Webhook Subscription ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Optional rotation reason","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateHmacSecretRequestBody"}}}},"responses":{"200":{"description":"HMAC secret key rotated successfully. The new key is shown once.","headers":{"Cache-Control":{"schema":{"type":"string"}},"Pragma":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateHmacSecretResponse"}}}},"400":{"description":"HMAC signing is not enabled for this webhook subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExpiredToken"},{"$ref":"#/components/schemas/InvalidToken"},{"$ref":"#/components/schemas/Unauthorized"}]}}}},"403":{"$ref":"#/components/responses/AccessDenied"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Secret rotation is limited to once every 5 minutes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
````
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.openloyalty.io/api-reference/webhook-subscription.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.