> For the complete documentation index, see [llms.txt](https://help.clickatell.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.clickatell.com/developers-documentation/custom-security-headers-for-webhook-callbacks.md).
# Custom Security Headers for Webhook Callbacks
Custom Security Headers allow you to add your own HTTP authentication headers to outbound webhook callbacks from One API. When Clickatell sends delivery-status or message notifications to your endpoint, these headers are automatically included in every request — enabling your API gateway to authenticate incoming webhooks without relying on basic authentication alone.
Use this when your API infrastructure:
* Requires custom header-based authentication (e.g., API keys, gateway tokens)
* Cannot be modified to support basic authentication
* Mandates multiple security headers for compliance or architectural reasons
**Key Facts**
| **Detail** | **Value** |
| -------------------------------- | ------------------------------------------------------------------------------------------------- |
| Maximum headers per callback URL | 5 |
| Configured separately for | Status callback URL and Reply callback URL |
| Header name max length | 64 characters |
| Header value max length | 512 characters |
| Allowed header name characters | Alphanumeric, hyphens (\`-\`), underscores (\`\_\`) |
| Storage | Encrypted at rest, cached after decryption |
| Compatibility | Works alongside Basic Auth — \*\*unless\*\* you set a custom \`Authorization\` header (see below) |
| Applies to | Status callbacks AND reply/message callbacks |
:exclamation:Headers are configured per callback URL, not per integration. If your integration has separate Status and Reply callback URLs, you configure headers independently for each.
**Prerequisites**
Before configuring custom headers, ensure you have:
1\. A Clickatell portal account with the required permission assigned to your user role.
2\. An active One API integration with a configured callback URL.
3\. Your header name(s) and value(s) ready — header values cannot be retrieved after saving.
:exclamation:Header values function as shared secrets. Generate cryptographically secure, high-entropy values. Store them securely on your side before saving — Clickatell cannot recover them.
**Setting Up Custom Headers**
Step 1: Navigate to Webhook Settings
1.1. Log into the Clickatell portal.
1.2. Navigate to your ‘One API integration settings’.
1.3. You'll see two separate ‘Custom Security Headers’ sections — one for your ‘Status Callback URL’ and one for your ‘Reply Callback URL’.
Step 2: Add a Header
2.1. In the relevant callback URL section (Status or Reply), click ‘Add Header’.
2.2. Fill in the form:
| **Field** | **Description** | **Rules** |
| ------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Header Name | The HTTP header name your gateway expects | Required. Alphanumeric + hyphens + underscores. Max 64 chars. Must be unique within this callback URL. |
| Header Value | The secret value for authentication | Required. Masked input. Max 512 chars. Cannot be viewed after saving. |
2.3. Review the warning: "Header values are stored encrypted and cannot be retrieved after saving. Ensure you have saved this value securely.”
2.4. Click ‘Save’.
Once successful, you'll see: "Header `` configured successfully."
Step 3: Repeat for Additional Headers
Add up to 5 headers per callback URL. Each header name must be unique within that callback URL.
Note: You can use the same header name on both your Status and Reply callback URLs — uniqueness is enforced per callback URL, not globally.
If you attempt to add a 6th header, you'll see: "Maximum of 5 custom headers allowed per callback URL."
Step 4: Configure Reply Callback Headers (if different)
If your Reply callback URL uses a different endpoint or requires different authentication, navigate to the ‘Reply Callback URL’ section and configure its headers separately. The two sets are fully independent.
**Example Configuration**
A typical setup for an enterprise API gateway might look like:
| **Header name** | **Purpose** |
| ---------------------- | -------------------------------------------------- |
| \`x-apigw-api-id\` | Identifies the target API at the gateway |
| \`X-Gravitee-Api-Key\` | Authenticates the request at the API gateway layer |
Once configured, every webhook callback from Clickatell to your endpoint will include:
{% code overflow="wrap" %}
````
```http
POST /your-webhook-endpoint HTTP/1.1
Host: api.yourcompany.com
Content-Type: application/json
x-apigw-api-id: dc2kaeblr5
X-Gravitee-Api-Key: 1ece3d95-82f6-47fd-9433-7ff530cd9a45
{ "messageId": "abc123", "status": "DELIVERED", ... }
```
````
{% endcode %}
**How It Works at Delivery Time**
When a message event occurs (delivery, failure, reply), the following happens:
1. Clickatell generates a webhook delivery event.
2. The platform checks if your integration has custom headers configured.
3. If yes — retrieves and decrypts your stored header values.
4. Injects all configured headers into the outbound HTTP request.
5. Sends the webhook to your callback URL with headers included.
6. Your API gateway validates the headers and processes the payload.
If header retrieval fails (e.g., transient infrastructure issue), the webhook is queued for automatic retry.
**Updating a Header Value**
Use this when you need to rotate a secret or update a compromised credential.
1. Navigate to ‘Custom Security Headers’ for the relevant callback URL in your integration settings.
2. Find the header you want to update.
3. Click "Update".
4. Enter the new header value (the old value is not displayed — it remains encrypted).
5. Click ‘Save’.
Once successful, you'll see: "Header `` updated successfully. New value will be used in all future webhook requests."
{% hint style="info" %}
Header values are cached for performance. After updating, there may be a brief period (typically seconds) where in-flight or immediately subsequent requests still use the previous value. This is the same behavior as updating Basic Auth credentials.
{% endhint %}
**Deleting a Header**
1. Navigate to ‘Custom Security Headers’ for the relevant callback URL in your integration settings.
2. Find the header you want to remove.
3. Click "Delete".
4. Confirm the deletion in the prompt.
Once successful, you'll see: "Header `` deleted successfully."
:exclamation:Once deleted, the header will no longer be included in outbound webhooks for that callback URL. Ensure your endpoint does not require this header before deleting, or webhook deliveries may be rejected by your gateway.
{% hint style="info" %}
If you delete the callback URL itself, all associated custom headers are automatically removed (cascade delete)
{% endhint %}
**Authentication Modes — What Gets Sent**
Your callback URL can use Basic Auth, Custom Headers, or both:
| **Configuration** | **What's Sent** |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Basic Auth only | Standard \`Authorization: Basic \\` header |
| Custom Headers only (no \`Authorization\` header name) | Your configured custom headers (no \`Authorization\` header) |
| Both configured (no \`Authorization\` header name in custom set) | \| \`Authorization: Basic \\` header \*\*plus\*\* all custom headers |
| Custom header named \`Authorization\` configured | Only\*\* your custom \`Authorization\` header — Basic Auth credentials are ignored |
| Neither configured | No authentication headers |
:exclamation: If you add a custom header with the name \`Authorization\`, this \*\*overrides\*\* your Basic Auth configuration for that callback URL. The platform will send your custom \`Authorization\` value instead of the Basic Auth credentials. This is by design — it allows you to use bearer tokens or other authorization schemes without removing your Basic Auth configuration.
Existing integrations are not affected. If you currently use Basic Auth and don't configure custom headers, nothing changes.
**Security & Compliance**
* Header values are encrypted at rest immediately upon creation or update.
* Decrypted values are held in memory only during webhook delivery, then discarded.
* No plain text header values appear in:
* Application logs
* Error messages
* Configuration files
* The Clickatell portal user interface (values are always masked)
**Troubleshooting**
| **Problem** | **Likely cause** | **Solution** |
| --------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Webhook rejected by your gateway (401/403) | Header value mismatch | Update the header with the correct value. Remember: you can't view stored values — re-enter from your records. |
| "Maximum of 5 custom headers allowed" | Limit reached | Delete an unused header from that callback URL before adding a new one. |
| "Header name already exists" | Duplicate name | Each header name must be unique within the same callback URL. Use a different name or update the existing one. |
| Headers not appearing in requests | Feature not enabled for your account | Confirm you have the Custom Security Headers permission. Contact Clickatell Support if needed. |
| Basic Auth stopped working | Custom \`Authorization\` header configured | If you have added a custom header named \`Authorization\`, it overrides Basic Auth. Remove the custom \`Authorization\` header to restore Basic Auth behavior. |
| Header rotation not taking effect immediately | Caching delay | Headers are cached for performance. Wait a few seconds and retry. This matches Basic Auth credential update behavior. |
| Webhook delivery delayed | Transient retrieval failure | The platform auto-retries. If persistent, check the Clickatell Status Page or contact Clickatell Support. |
**Frequently Asked Questions**
Q: Can I view my saved header values?
A: No. Header values are encrypted immediately and cannot be retrieved or displayed. Always save them securely before configuring.
Q: Do custom headers apply to all callback types?
A: Yes, but they are configured independently. You set headers separately for your Status callback URL and your Reply callback URL. Each set is injected into its respective outbound requests.
Q: Will this break my existing Basic Auth setup?
A: No — with one exception. If you add a custom header named \`Authorization\`, it overrides Basic Auth for that callback URL. All other custom header names coexist with Basic Auth without conflict.
Q: How quickly do changes take effect?
A: Nearly immediately. Due to caching, there may be a brief period (typically seconds) where the previous value is still used. This matches existing Basic Auth credential update behavior.
Q: Is there a cost for this feature?
A: There is no additional charge for this feature. Custom Security Headers are included as part of the One API platform.
Q: Can I use the same header name on both my Status and Reply callback URLs?
A: Yes. Uniqueness is enforced per callback URL. Your Status and Reply callback URLs can have the same header names with different values.
Q: Can I have different headers for Status vs Reply callbacks?
A: Yes. Headers are configured per callback URL. If your Status and Reply endpoints have different security requirements, configure each independently.
Q: What happens if I delete a callback URL that has custom headers?
A: All custom headers associated with that callback URL are automatically deleted (cascade).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.clickatell.com/developers-documentation/custom-security-headers-for-webhook-callbacks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.