Webhooks

Authentication

Authentication can be done in two ways and all requests should include this (otherwise you'll get a 401 error). This will work for both Webhooks and API calls.

1. Header based auth

You need to pass your token as header: X-API-Key: your-token-key

2. Query based Auth

You need to pass your token as query parameter: ?_invox-api-key=your-token-key

Your token key must be generated from your INVOX account. You can create and manage token keys in the Integrations section of your INVOX dashboard.

All requests should include the following parameters:

_scope, which can be either calls or forms. If not included, it will fallback to calls.
hookUrl, which is the hook URL we'll call on either a call ended or form submitted

You can do a GET test request (handshake) that on:

Scope	Method	Endpoint
Calls	GET	https://app.invox.eu/integrations/webhook/handshake?_scope=calls
Forms	GET	https://app.invox.eu/integrations/webhook/handshake?_scope=forms

Response

If auth is OK, the response should be an array with the account's name:

{
"name": "invox.eu"
}

If the auth fails, you'll get a 401:

{
"message": "Unauthorized"
}

Subscribing to a Webhook

You can subscribe to a webhook by doing a POST request

Scope	Method	Endpoint
Calls	POST	https://app.invox.eu/integrations/webhook/subscribe?_scope=calls
Forms	POST	https://app.invox.eu/integrations/webhook/subscribe?_scope=forms

hookUrl parameter is required and can be passed either by url query (encoded!):

curl --request POST \
--url 'https://app.invox.eu/integrations/webhook/subscribe?hookUrl=https%3A%2F%2Fmy-site.com%2Fwebhook-handler&_scope=calls' \
--header 'x-api-key: my-api-key'

or by form data:

curl --request POST \
--url 'https://app.invox.eu/integrations/webhook/subscribe?_scope=calls' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'x-api-key: my-api-key' \
--data hookUrl=https://my-site.com/webhook-handler

Once you subscribed, you'll get a request from us any time a Call is made or a Form is received.

The data will be a json with this shape:

Calls:

[
    {
        "key": "",
        "id": "",
        "call_id": "",
        "date": "",
        "duration": "",
        "status": "",
        "caller": "",
        "receivingnumber": "",
        "destinationnumber": "",
        "source": "",
        "keyword": "",
        "referrer": "",
        "medium": "",
        "page": "",
        "campaign": "",
        "campaignid": "",
        "adgroupid": "",
        "network": "",
        "matchtype": "",
        "creative": "",
        "adposition": "",
        "device": "",
        "recording_uri": "",
        "gclid": "",
        "gacid": "",
        "gbraid": "",
        "wbraid": "",
        "utm_id": "",
        "utm_term": "",
        "utm_content": "",
        "utm_source": "",
        "fbclid": "",
        "ttclid": "",
        "account": "",
        "reason": "",
        "client_sentiment": "",
        "operator_sentiment": "",
        "summary": "",
    }
]

Forms:

[
    {
        "key": 124,
        "id": 124,
        "call_id": 670542,
        "form_id": 124,
        "date": "2026-04-20T09:59:10+03:00",
        "account": "string",
        "receiving_number": "string",
        "receiving_email": "string",

        "mapped": {
            "name": ""
            "email": ""
            "phone": ""
            "message": ""
            "referer": ""
            "referer_domain": ""
            "original_referer": ""
            "traffic_source": ""
            "first_traffic_source": ""
            "organic_source": ""
            "organic_source_alt": ""
            "remote_url": ""
            "remote_url_base": ""
            "remote_form_id": ""
            "user_ip": ""
            "user_agent": ""
            "landing_page": ""
            "landing_page_base": ""
            "utm_source": ""
            "utm_medium": ""
            "utm_term": ""
            "utm_content": ""
            "utm_campaign": ""
            "first_utm_source": ""
            "first_utm_medium": ""
            "first_utm_term": ""
            "first_utm_content": ""
            "first_utm_campaign": ""
            "fbclid": ""
            "msclkid": ""
            "gclid": ""
            "wbraid": ""
            "gbraid": ""
            "gaclientid": ""
            "fbc": ""
            "fbp": ""
            "extra_field_1": ""
            "extra_field_2": ""
            "extra_field_3": ""
            "extra_field_4": ""
            "extra_field_5": ""
            "extra_field_6": ""
            "extra_field_7": ""
            "extra_field_8": ""
            "extra_field_9": ""
            "extra_field_10": ""
        },

        "raw": {
            "handl_handl_original_ref": "",
            "handl_handl_landing_page": "",
            "handl_handl_landing_page_base": "",
            "handl_handl_ip": "",
            "handl_handl_ref": "",
            "handl_handl_url": "",
            "handl_handl_ref_domain": "",
            "handl_handl_url_base": "",
            "handl_organic_source": "",
            "handl_organic_source_str": "",
            "handl_user_agent": "",
            "handl_traffic_source": "",
            "handl_first_traffic_source": "",
            "handl_handlID": "",
            "handl__fbp": "",
        }
    }
]

Note that inside mapped empty keys won't be included.

Raw object contains all the data we receive from a form so the content will vary based on your form configuration.

Unsubscribing from a webhook

You can unsubscribe from a webhook (i.e. we won't do any requests on it anymore) either from the UI in this page or by calling the /unsubscribe endpoint with a DELETE method. The request must include hookUrl parameter!

Scope	Method	Endpoint
Calls	DELETE	https://app.invox.eu/integrations/webhook/unsubscribe?_scope=calls
Forms	DELETE	https://app.invox.eu/integrations/webhook/unsubscribe?_scope=forms

curl --request DELETE \
    --url 'https://invox.ddev.site/integrations/webhook/unsubscribe?hookUrl=https%3A%2F%2Fmy-site.com%2Fwebhook-handler&_scope=calls' \
    --header 'x-api-key: my-api-key'