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`.
url	(string, conditional, max=1000) The URL to which the webhook payload will be sent. Required for webhooks of type `https`.
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.
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`. 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.
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",
            "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",
                "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
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	400
528	webhook_signature_not_found	The webhook_signature_id does not correspond to an existing record	404

Adding a webhook​

Contents​

Overview​

Version-specific information​

Permissions and Authentication​

Headers​

HTTP Parameters​

Example response JSON​

Possible error responses​