Adding a webhook

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

Overview

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

This endpoint creates a new webhook configuration for a chain. The webhook will be triggered whenever the specified event occurs and will send a POST request containing the event payload to the configured URL.

Webhooks of type https store their own URL and credentials directly. To enable HMAC signature verification on an https webhook, create a webhook signature key using add-webhook-signature and pass its ID in the webhook_signature_id parameter.

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
chain_id	(integer, mandatory) The ID of the chain to which the webhook belongs.
event_name	(string, mandatory, max=128) The name of the event that triggers the webhook. See the available webhook events for valid values.
type	(string, mandatory, max=128) The type of webhook. For standard HTTPS webhooks, use `https`. The email provider types `ses` and `smtp` are also accepted on the `email_verification_otp` and `email_verification_deeplink` events, and configure which email service delivers a chain's verification emails - see sending verification emails from your own email provider.
url	(string, conditional, max=1000) The URL to which the webhook payload will be sent. Required for webhooks of type `https`. For webhooks of type `smtp` this is the address of the SMTP server, for example `smtp://mail.example.com:587`, and is required. Not used for type `ses`.
filter	(string, optional, max=2048) A filter expression that restricts when the webhook fires. The filter format is a keyword followed by a comma-separated key=values pair, for example `campaign types=signup,loyalty`.
identifier_key	(string, optional, max=128) An identifier key or username for authentication with the webhook recipient. For webhooks of type `smtp`, the username for the SMTP server.
identifier_secret	(string, optional, max=256) An identifier secret or password for authentication with the webhook recipient. For webhooks of type `smtp`, the password for the SMTP server. 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`. See add-webhook-signature for creating a webhook signature key.
campaign_id	(integer, optional) The ID of a campaign to associate with this webhook. The campaign must belong to the same chain.
task_id	(integer, optional) The ID of a task to associate with this webhook. The task must belong to the same chain.
event_trigger	(string, optional, max=512) An event trigger expression for additional event filtering. For webhooks of type `ses` or `smtp`, an optional subject line which replaces the default subject of the verification email.
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. If not set, the chain's own email address is used.
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 (`ses` or `smtp` for the email events; an SMS provider type for the phone event). A chain can have one primary and one standby per event, and a standby can only be added once a live primary exists. A webhook without a `delivery_role` sends unconditionally.
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` (default), compact JSON is used.
payload_spaaza_api_version	(string, optional, max=32) The Spaaza API version to use for the webhook payload format. Defaults to `1.4.8`.

Example response JSON

The endpoint returns JSON showing the details of the created 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-26T10: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-26T10:00:00+00:00",
            "payload_spaaza_api_version": "1.4.8",
            "send_from": null,
            "task_id": null,
            "type": "https",
            "url": "https://example.com/webhooks/spaaza",
            "webhook_signature": {
                "active": true,
                "chain": {
                    "id": 1743,
                    "name": "ACME Retail"
                },
                "created_date": "2026-06-26T09:55:00+00:00",
                "delivery_role": null,
                "deleted": false,
                "id": 56,
                "last_modified_date": "2026-06-26T09:55:00+00:00",
                "value": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
            }
        },
        "result_type": "add-webhook"
    }
}

Possible error responses

Code	Name	Description	HTTP Status
3	http_vars_missing	Required parameter is missing (chain_id, event_name, or type)	400
6	no_valid_session	No valid session key provided or session has expired	401
13	http_request_method_non_POST_not_allowed	Only HTTP POST allowed for this API call	405
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 campaign, task, or webhook signature does not match the chain	400
417	string_parameter_too_long	One or more string parameters exceeds the maximum length	400
433	invalid_url	The url is missing or 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 an email provider type is used on an event other than the email verification events	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, or a `standby` is added while there is no live `primary`	400

Adding a webhook​

Contents​

Overview​

Version-specific information​

Permissions and Authentication​

Headers​

HTTP Parameters​

Example response JSON​

Possible error responses​