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.
type	(string, optional, max=128) The type of webhook. Can only be changed between the email provider types `ses` and `smtp`, to move a chain's verification emails between Spaaza's own email service and the chain's own email provider - see sending verification emails from your own email provider. Every other type is fixed for the life of the webhook; create a new webhook instead.
url	(string, optional, max=1000) The URL to which the webhook payload will be sent. For webhooks of type `smtp`, the address of the SMTP server, for example `smtp://mail.example.com:587`.
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. A webhook with `delivery_role` `primary` cannot be disabled while its `standby` is still live.
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. For webhooks of type `ses` or `smtp`, the email address the verification email is sent from; must be a valid email address. Pass an empty string or `null` to clear.
delivery_role	(string, optional) The webhook's position in a verification delivery pair, either `primary` or `standby`. The primary sends; the standby is held back and used only when the primary fails to accept the message - see backup email provider. Only accepted on the `email_verification_otp`, `email_verification_deeplink` and `phone_number_verification` events, and only on a type that delivers that event. A chain can have one primary and one standby per event, and a standby requires a live primary. Pass an empty string or the string `null` to remove the role; a JSON `null` leaves the role unchanged. A `primary` cannot be unroled, re-roled or moved to another `event_name` while its `standby` is still live - use swap-webhook-delivery-roles to exchange the two roles.

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",
            "delivery_role": null,
            "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",
                "delivery_role": null,
                "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
433	invalid_url	The url is not a valid SMTP server address for a webhook of type `smtp`	400
493	webhook_event_name_invalid	The event_name value is not a recognised webhook event	400
494	webhook_type_invalid	The type value is not a recognised webhook type, or the type change is not between `ses` and `smtp`, or an email provider type is used on an event other than the email verification events	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
534	invalid_parameter	The send_from value is not a valid email address for a webhook of type `ses` or `smtp`	400
562	webhook_delivery_role_conflict	The delivery_role is not `primary` or `standby`, is used on an event or type that does not support it, the chain already has a webhook with that role on this event, a `standby` has no live `primary`, or the change would leave a live `standby` without a `primary`	400