> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/webhooks/subscriptions-apis.md). # Subscriptions APIs \[ Base URL: `api.ggwp.com` ] ## **Authentication** Please refer to the [section here](/api-docs-chat/standard-package.md#authentication) for authentication. ## **New Version v1.1** A new version `1.1` has been released with minor changes. Changelog: * New webhook event subscriptions would default to the `1.1` version * Events sent to the webhook URLs will have the payload in string format without whitespaces * Note: Support for version `1.0` will continue. This version requires additional stripping of the whitespaces in the payload while calculating the HMACs for [payload validation](/webhooks/receiving-events.md#request-validation). ## **APIs** ### **1. Subscribe to an event** `POST` /webhook/v1/subscriptions This API subscribes a customer to an event generated by the GGWP platform. **Parameters** * **url:** URL to receive the call upon event trigger * **enabled:** Boolean `true` or `false` denoting if the webhook should be in enabled state. Defaults to `true` if not passed. * **event\_type:** Event type to subscribe, as mentioned under [Webhook Events](/webhooks/webhook-events.md) * **version:** Denotes the payload version. Defaults to `1.1` if not passed. * (OPTIONAL) **headers:** Key-value pairs representing header name and value. * Header name should contain only letters, numbers and hyphens. * Header name can be up to 256 characters long, and the value up to 1024 characters long. * The following headers are reserved and not accepted * `content-type` * `x-ggwp-hmac-sha256` * `host` * `content-length` * `connection` * `transfer-encoding` * `expect` Example: {% code overflow="wrap" %} ```json { "url": "https://example.com/customerapi", "enabled": true, "event_type": "player-sanctioned", "version": "1.1", "headers": { "Authorization": "Bearer " } } ``` {% endcode %} **Output** * 201 {% code overflow="wrap" %} ```json { "id": "85537238-1053-4057-877e-131838c789d8", "url": "https://example.com/customerapi", "enabled": true, "event_type": "player-sanctioned", "version": "1.1", "headers": { "Authorization": "Bearer " }, "created_at": "2024-02-27T17:02:39", "updated_at": "2024-02-27T17:02:39", "secret_key": "xxxxxxxxxxxxxx" } ``` {% endcode %} The `secret_key` returned in this request is expected to be stored at the customer's end. Every subscription will have its own unique `secret_key`. This is used to validate if the URL is being called via a legitimate party, i.e., GGWP in this case. More is discussed in the [Receiving Events](/webhooks/receiving-events.md) section. * 400 * If any of these fields are missing: `url`, `event_type` * Malformed URL sent in `url` parameter * Invalid `event_type` is sent * Invalid `version` is sent * Invalid value for `enabled` is sent * Invalid value for `headers` is sent * 403 * Invalid or missing API key * 500 * Something went wrong on the server side. The request can be retried again after a few min. In case it persists then reach out to your GGWP account manager. ### 2. List all the subscriptions `GET` /webhook/v1/subscriptions The API lists all the webhooks a customer is subscribed to. It does not return the `secret_key` though. Look at the list below to check the API get to get the secret key. **Output** * 200 {% code overflow="wrap" %} ```json [ { "id": "85537238-1053-4057-877e-131838c789d8", "url": "https://example.com/customerapi", "enabled": true, "event_type": "player-sanctioned", "version": "1.1", "headers": { "Authorization": "Bearer " }, "created_at": "2024-02-27T16:16:25", "updated_at": "2024-02-27T16:16:25" }, { "id": "de48a6a4-8bb6-470e-9990-2fd83f3ccbb5", "url": "https://example.com/customerapi", "enabled": true, "event_type": "player-reinstated", "version": "1.1", "headers": {}, "created_at": "2024-02-27T16:16:25", "updated_at": "2024-02-27T16:16:25" }, ... ] ``` {% endcode %} * 403 * Invalid or missing API key ### 3. Update a subscription `PATCH` /webhook/v1/subscriptions/:id Updates the webhook subscription attributes. **Parameters** * **id:** Sent as path parameter. This is the ID of the event subscription to be modified. * **event\_type:** Update the event type to another event from the list [here](/webhooks/webhook-events.md) * **url:** Update the URL to receive the call upon event trigger * **enabled:** Enable or disable the subscription by sending `true` or `false` * **version:** Change the version of the subscription service. * (OPTIONAL) **headers:** Key-value pairs representing header name and value. Example: {% code overflow="wrap" %} ```json { "event_type": "player-sanctioned", "url": "https://example.com/customerapi", "enabled": true, "version": "1.1", "headers": { "Authorization": "Bearer " } } ``` {% endcode %} **Output** * 200 {% code overflow="wrap" %} ```json { "id": "85537238-1053-4057-877e-131838c789d8", "url": "https://example.com/customerapi", "enabled": true, "event_type": "player-sanctioned", "version": "1.1", "headers": { "Authorization": "Bearer " }, "created_at": "2024-02-27T16:16:25", "updated_at": "2024-02-27T16:16:25" } ``` {% endcode %} * 400 * Invalid `event_type` is sent * Invalid `version` is sent * Invalid value for `enabled` is sent * Invalid value for `headers` is sent * 403 * Invalid or missing API key * 500 * Something went wrong on the server side. The request can be retried again after a few minutes. In case it persists then reach out to your GGWP account manager. ### **4. Delete a subscription** `DELETE` /webhook/v1/subscriptions/:id Delete a subscription with the given ID. **Parameters** * **id:** Sent as path parameter. This is the ID of the event subscription to be deleted. **Output** * 200 {% code overflow="wrap" %} ```json {"success": true} ``` {% endcode %} * 403 * Invalid or missing API key * 404 * Subscription not found * 500 * Something went wrong on the server side. The request can be retried again after a few minutes. In case it persists then reach out to your GGWP account manager. ### **5. Rotate Secret** `POST` /webhook/v1/subscriptions/:id/secret Rotates the subscription secret key. Upon successful API call the secret key is updated immediately. **Parameter** * **id:** Sent as path parameter. This is the ID of subscription for which the key is to be rotated **Output** * 200 {% code overflow="wrap" %} ```json { "secret_key": "yyyyyyyyyyyyyy" } ``` {% endcode %} * 403 * Invalid or missing API key * 500 * Something went wrong on the server side. The request can be retried again after a few minutes. In case it persists then reach out to your GGWP account manager. ### **6. Get Secret** `GET` /webhook/v1/subscriptions/:id/secret Returns the secret key for the given subscription `id` **Parameter** * **id:** Sent as path parameter. This is the ID of subscription for which the secret key is requested for **Output** * 200 {% code overflow="wrap" %} ```json { "secret_key": "yyyyyyyyyyyyyy" } ``` {% endcode %} * 403 * Invalid or missing API key