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
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.
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 <name> 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:
How It Works at Delivery Time
When a message event occurs (delivery, failure, reply), the following happens:
Clickatell generates a webhook delivery event.
The platform checks if your integration has custom headers configured.
If yes — retrieves and decrypts your stored header values.
Injects all configured headers into the outbound HTTP request.
Sends the webhook to your callback URL with headers included.
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.
Navigate to ‘Custom Security Headers’ for the relevant callback URL in your integration settings.
Find the header you want to update.
Click "Update".
Enter the new header value (the old value is not displayed — it remains encrypted).
Click ‘Save’.
Once successful, you'll see: "Header <name> updated successfully. New value will be used in all future webhook requests."
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.
Deleting a Header
Navigate to ‘Custom Security Headers’ for the relevant callback URL in your integration settings.
Find the header you want to remove.
Click "Delete".
Confirm the deletion in the prompt.
Once successful, you'll see: "Header <name> deleted successfully."
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.
If you delete the callback URL itself, all associated custom headers are automatically removed (cascade delete)
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 <encoded>` 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 <encoded>` 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
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).
Last updated