> 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/subscribe-to-a-webhook.md).
# Subscribe to a webhook
Management\
\
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":"http","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","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":["code","message"],"properties":{"code":{"type":"integer"},"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"}}}}}}
````
---
# 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, and the optional `goal` query parameter:
```
GET https://help.openloyalty.io/api-reference/webhook-subscription/subscribe-to-a-webhook.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.