Using Headers in Webhook Block for Secure and Structured API Calls

Headers in Webhook Block

When sending API requests through a Webhook block in your bot flow, headers play a vital role. They carry additional information that helps third-party systems identify, authorize, and understand your request.
Let’s walk through what headers are, why they’re needed, how to use them, and a few examples to make things easier.
​
Learn more about webhooks: Introduction to Webhook Block in GC 

What are Headers?   

Headers are key-value pairs that are sent along with your webhook request. Think of them as special instructions or identity cards that travel with your request, telling the receiving system who you are and what kind of data you’re sending.

Here’s how a header looks:
  1. Key: Authorization
  2. Value: Bearer your-access-token
Another example:
  1. Key: Content-Type
  2. Value: application/json
These headers are not visible to the end user; they work behind the scenes to make the connection secure, clear, and properly formatted. 



When do you use Headers?   

You’ll typically use headers when:
  1. The API you’re calling requires authentication (e.g., OAuth or API tokens).
  2. You need to set the content type for your request (usually JSON).
  3. You’re working with a service like Zoho, which may need extra details like orgId or portalId.
  4. You want to safely pass sensitive system-level information that should not appear in the request body or URL.
 You can add headers in the “Headers” section of the Webhook block, where you define each key and its corresponding value. 

Why are Headers important?   

Headers are essential for most API calls because they: (Suggestion: Header can be used to mask sensitive information while sending to a third party service. - need to confirm with dev)
  1. Authenticate who is sending the request.
  2. Define what format the request body is in (JSON, XML, etc.).
  3. Pass extra system-level information (like organization or portal IDs).
  4. Ensure that the server understands how to handle your request securely.
Without the right headers, many APIs will reject your request or return an error. 

Commonly Used Headers
Commonly Used Headers
Here are some headers you’ll often use when calling APIs:

Header Key
Example Value
Purpose
Authorization
Bearer ya29.a0AfH6…
Authenticates the request using an access token
Content-Type
application/json
Tells the server the format of the request body
orgId
1234567890
Identifies the Zoho organization making the call
portalId
zylker-support
Used for department-level identification

 You can add up to 20 headers per webhook request, giving you the flexibility to meet any API requirement. 
Example Use Case
Let’s say you want your bot to update a support ticket using the Zoho Desk API. You’ll need to send an authenticated PUT request.

Here’s what your headers might look like:
  1. Authorization: Bearer 1000.abcdeXYZ.your-access-token
  2. orgId: 123456789
  3. Content-Type: application/json
These headers ensure that:
  1. The system knows who you are (Authorization).
  2. It knows you’re part of a specific Zoho organization (orgId).
  3. It understands that your request body is formatted in JSON (Content-Type).
Without these headers, Zoho’s servers would not be able to process your request.

Are Headers secure?   

Yes, headers are invisible to the end users interacting with your bot. This means you can safely include confidential information like:
  1. OAuth tokens
  2. API keys
  3. Internal organization IDs
However, it’s still important to treat this data carefully:
  1. Never expose headers in bot messages.
  2. Store tokens securely and rotate them periodically.
  3. Use HTTPS endpoints to encrypt all communication.
 

Benefits of using Headers   

  1. Securely pass authentication credentials
  2. Ensure your request is formatted correctly
  3. Communicate additional context to external systems
  4. Keep sensitive info hidden from users
  5. Enable access to protected data or APIs

Tips for using Headers   

  1. Always check the API documentation to see which headers are required
  2. Use “Bearer” before your token if the API expects it (e.g., Bearer abc123token)
  3. Don’t include unnecessary headers, only what’s needed
  4. Use test environments first before using headers in live scenarios
  5. Refresh tokens as needed, especially for OAuth-based systems
​
Learn more about webhooks: Introduction to Webhook Block in GC