Get the Integrator ID

The Integrator ID and Webhook Secret are fundamental components for managing your integration with Caliza. The Integrator ID uniquely identifies your account and is required for most API operations, while the Webhook Secret is essential for securing and verifying the notifications (webhooks) sent to your system.

This guide explains how to retrieve these credentials using your access token and how to configure your webhook URL to start receiving real-time event updates.

Prerequisites

Before you start, ensure you have the following:

The client_id, client_secret that you can get on your Caliza dashboard.
The access_token that you can get when you authenticate with the Caliza API. To know more about the authentication process, access the Authenticate documentation.

Get your Integrator ID

To get your Integrator ID on Caliza, follow these steps:

With your credentials ready, client_id, client_secret and access_token, run this command on the terminal:

curl --location GET 'https://api.sandbox.caliza.com/core-api/v1/integrators/me' \
--header 'Authorization: Bearer YOUR_TOKEN' \

{
        "id": "6920925fdbadfe09b1bf9e5e",
        "name": "Name_of_Your_Integrator",
        "address": {
                "streetOne": "You_Address_123",
                "streetTwo": "Your_Address_456",
                "geolocation": null,
                "city": "Your_City",
                "zipcode": "Your_Zipcode",
                "state": "Your_State",
                "country": "Your_Country_Code"
        },
        "document": "34567892000795",
        "telephones": [
                "Your_Telephone_Number"
        ],
        "contract": {
                "price": 100,
                "transactionFee": 0,
                "transactionFeeMode": "FIXED"
        },
        "files": null,
        "active": true,
        "callbackUrl": "",
        "contactEmails": [
                "[email protected]"
        ],
        "credentials": {
                "clientId": "integrator-Name_of_Your_Integrator",
                "clientSecret": "Your_Client_Secret"
        },
        "banking": {
                "code": null,
                "agency": null,
                "account": null,
                "pixKey": "${PROVIDERS_GENIAL_DEFAULT_PIX_KEY}",
                "pixKeyType": null
        },
        "webhookSecret": null,
        "deviationConfig": null,
        "customerSignupId": "6920925fdbadfe09b1bf9e5f",
        "marketExecutionType": "EXECUTE_IMMEDIATELY"
}

The response contains your Integrator ID, which you can find in the id field. In this example, the Integrator ID is 6920925fdbadfe09b1bf9e5e. Use this ID for any API calls that require the Integrator ID.

Integrator webhook secret

To get your Integrator Webhook Secret, use the same API call as in the preceding step. The response includes a field called webhookSecret. If this field is null, it means no webhook secret exists for your integrator. To get your webhook secret, you can run the following command:

curl -s --location --request GET 'https://api.sandbox.caliza.com/core-api/v1/integrators/me' \              ~
        --header 'Authorization: Bearer YOUR_TOKEN'

{
        "id": "6920925fdbadfe09b1bf9e5e",
        "name": "Name_of_Your_Integrator",
        "address": {
                "streetOne": "Your_Address_123",
                "streetTwo": "Your_Address_456",
                "geolocation": null,
                "city": "Your_City",
                "zipcode": "Your_Zipcode",
                "state": "Your_State",
                "country": "Your_Country_Code"
        },
        "document": "34567892000795",
        "telephones": [
                "Your_Telephone_Number"
        ],
        "contract": {
                "price": 100,
                "transactionFee": 0,
                "transactionFeeMode": "FIXED"
        },
        "files": null,
        "active": true,
        "callbackUrl": "",
        "contactEmails": [
                "[email protected]"
        ],
        "credentials": {
                "clientId": "integrator-Name_of_Your_Integrator",
                "clientSecret": "Your_Client_Secret"
        },
        "banking": {
                "code": null,
                "agency": null,
                "account": null,
                "pixKey": "${PROVIDERS_GENIAL_DEFAULT_PIX_KEY}",
                "pixKeyType": null
        },
        "webhookSecret": "AXxDmWTa0fcdoT6CsR5DhmijZaaaHwY+77sVZs/x4ro=",
        "deviationConfig": null,
        "customerSignupId": "6920925fdbadfe09b1bf9e5f",
        "marketExecutionType": "EXECUTE_IMMEDIATELY"
}

This will get you the integrator details, including the webhookSecret if it exists. If the webhookSecret is null, you need to set it using the appropriate API endpoint to generate a new webhook secret Where the webhookSecret field contains your webhook secret, in this case the value AXxDmWTa0fcdoT6CsR5DhmijZaaaHwY+77sVZs/x4ro=.

Integrator webhook

To set or update your Integrator Webhook URL, you can use the following API call:

curl --location PATCH 'https://api.sandbox.caliza.com/core-api/v1/integrators/{{integrator_id}}/webhooks' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \

This command updates the webhook URL associated with your integrator. Make sure to replace integrator_id with your actual Integrator ID and YOUR_TOKEN with your valid access token. Usually, this command returns no content, but it updates the webhook URL of your integrator. If you want to look for more details, you can add the -v flag to the cURL command to see the response headers and status code.

curl -v --location --request PATCH 'https://api.sandbox.caliza.com/core-api/v1/integrators/6920925fdbadfe09b1bf9e5e/webhooks' \
        --header 'Authorization: Bearer YOUR_TOKEN' \
        --header 'Content-Type: application/json' \
        --data '{
        "url": "https://webhook.site/42163841-7cf6-4542-ae19-c1c48c7b11be"
    }'

< HTTP/2 204
< date: Tue, 25 Nov 2025 16:21:25 GMT
< expires: 0
< cache-control: no-cache, no-store, max-age=0, must-revalidate
< access-control-allow-headers: Content-Type, Accept, X-Requested-With, remember-me, Authorization
< x-xss-protection: 1; mode=block
< pragma: no-cache
< x-frame-options: DENY
< access-control-expose-headers: Content-Type, Content-Disposition, Content-Length
< caliza-trace-id: 459455e44d7a0d21
< vary: Origin
< vary: Access-Control-Request-Method
< vary: Access-Control-Request-Headers
< access-control-allow-credentials: true
< x-content-type-options: nosniff
< strict-transport-security: max-age=31536000 ; includeSubDomains
< access-control-allow-methods: POST, GET, OPTIONS, DELETE, PUT, PATCH
< access-control-max-age: 3600
<
* Connection #0 to host api.sandbox.caliza.com left intact

This indicates that the webhook URL has been successfully updated for your integrator.

Next Steps

Authenticate with the Caliza API

Authenticate with Caliza API.

Manage beneficiaries

Manage your beneficiaries.

Create virtual accounts

Manage your virtual accounts.

Manage Recipients

Manage your Recipients.