Updating a webhook

Overview
Version-specific information
Permissions and Authentication
Headers
HTTP Parameters
Example response JSON
Possible error responses

Overview

Call name: alter-webhook
Endpoint URL: https://{API hostname}/internal/alter-webhook
Request methods: PUT
Request Content-Type: application/x-www-form-urlencoded or application/json
Response Content-Type: application/json
Auth required: yes

This endpoint updates an existing webhook configuration. Only the parameters that are passed will be updated; other fields remain unchanged.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version	Change details
N/A	N/A

Permissions and Authentication

This API call requires a valid Spaaza session. See the authentication page for more details. The session can be as follows:

Admin authentication: The performing user needs to be logged in and have write access to the chain to which the webhook belongs.

Headers

The following headers can/must be passed to the API call:

Parameter	Description
N/A	N/A

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
id	(integer, mandatory) The ID of the webhook configuration to update.
chain_id	(integer, mandatory) The ID of the chain to which the webhook belongs. Must match the chain of the webhook being updated.
event_name	(string, optional, max=128) The name of the event that triggers the webhook. See the available webhook events for valid values.
url	(string, optional, max=1000) The URL to which the webhook payload will be sent.
filter	(string, optional, max=2048) A filter expression that restricts when the webhook fires.
active	(boolean, optional) Whether the webhook is active. Set to `false` to disable the webhook without deleting it.
identifier_key	(string, optional, max=128) An identifier key or username for authentication with the webhook recipient.
identifier_secret	(string, optional, max=256) An identifier secret or password for authentication with the webhook recipient. The value is obfuscated in API responses.
webhook_signature_id	(integer, optional) The ID of a webhook signature key to use for HMAC signature verification. Only applicable for webhooks of type `https`. Pass an empty string or `null` to remove the signature. See add-webhook-signature for creating a webhook signature key.
campaign_id	(integer, optional) The ID of a campaign to associate with this webhook. Pass an empty string or `null` to remove the association. The campaign must belong to the same chain.
task_id	(integer, optional) The ID of a task to associate with this webhook. Pass an empty string or `null` to remove the association. The task must belong to the same chain.
event_trigger	(string, optional, max=512) An event trigger expression for additional event filtering. Pass an empty string or `null` to clear.
applies_legacy_hmac	(boolean, optional) Controls the format of the JSON payload used when computing the HMAC signature. When `true`, the signature is computed over prettified JSON; when `false`, compact JSON is used.
payload_spaaza_api_version	(string, optional, max=32) The Spaaza API version to use for the webhook payload format.
send_from	(string, optional) A sender identifier. Pass an empty string or `null` to clear.

Example response JSON

The endpoint returns JSON showing the updated webhook configuration. An example response is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "webhook": {
            "active": true,
            "applies_legacy_hmac": false,
            "campaign_id": null,
            "created_date": "2026-06-20T10:00:00+00:00",
            "event_name": "shopper.voucher-issued",
            "event_trigger": null,
            "filter": null,
            "id": 1234,
            "identifier_key": null,
            "identifier_secret": null,
            "is_default": false,
            "last_modified_date": "2026-06-26T12:30:00+00:00",
            "last_updated_by": {
                "name": "Admin User",
                "user_id": 213112
            },
            "payload_spaaza_api_version": "1.4.8",
            "send_from": null,
            "task_id": null,
            "type": "https",
            "url": "https://example.com/webhooks/spaaza-updated",
            "webhook_signature": {
                "active": true,
                "chain": {
                    "id": 1743,
                    "name": "ACME Retail"
                },
                "created_date": "2026-06-20T09:55:00+00:00",
                "deleted": false,
                "id": 56,
                "last_modified_date": "2026-06-20T09:55:00+00:00",
                "value": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
            }
        },
        "result_type": "alter-webhook"
    }
}

Possible error responses

Code	Name	Description	HTTP Status
3	http_vars_missing	Required parameter is missing (id or chain_id)	400
6	no_valid_session	No valid session key provided or session has expired	401
68	permission_denied_or_non_existent	User has insufficient permissions or the chain does not exist	403
76	chain_id_invalid	The chain_id passed must be an integer	400
405	entity_mismatch	The webhook does not belong to the specified chain	400
417	string_parameter_too_long	One or more string parameters exceeds the maximum length	400
493	webhook_event_name_invalid	The event_name value is not a recognised webhook event	400
495	webhook_not_found	No webhook found for the specified ID	400
528	webhook_signature_not_found	The webhook_signature_id does not correspond to an existing record	404