Skip to Content
DestinationsOtherWebhook

Webhook

Send data to any HTTP endpoint. Use Zeotap to integrate with custom APIs, internal services, or any system that accepts JSON payloads over HTTP.

Prerequisites

  • An HTTP endpoint that accepts POST, PUT, or PATCH requests
  • The endpoint must be reachable from Zeotap
  • An authorization header value or API key (if the endpoint requires authentication)

Authentication

Webhook supports two authentication methods. Pick the one your endpoint requires.

Authorization Header

Send static credentials as request headers. Both fields are optional — use whichever your endpoint requires.

FieldTypeRequiredDescription
Authorization HeaderPasswordNoValue for the Authorization header (e.g., Bearer your-token)
API KeyPasswordNoAPI key sent in the X-Api-Key header (optional, for endpoints that use API key authentication)

OAuth 2.0 (Client Credentials)

For endpoints protected by an OAuth2 authorization server, Zeotap fetches an access token using the client-credentials grant  and sends it as an Authorization: Bearer <token> header on every request. The token is cached and refreshed automatically before it expires (with a 5-minute safety margin), and re-fetched if the endpoint rejects it with a 401 or 403.

This is a machine-to-machine flow — there is no interactive login or redirect. You supply your token endpoint and client credentials directly.

FieldTypeRequiredDescription
Token URLTextYesOAuth2 token endpoint that issues access tokens (e.g., https://auth.example.com/oauth/token)
Client IDTextYesOAuth2 client ID issued by your authorization server
Client SecretPasswordYesOAuth2 client secret issued by your authorization server
ScopeTextNoSpace-separated list of OAuth2 scopes to request (e.g., read write)
AudienceTextNoAudience parameter required by some providers (e.g., Auth0)

The token request is sent as application/x-www-form-urlencoded with grant_type=client_credentials, client_id, client_secret, and the optional scope / audience parameters.

Configuration

FieldTypeRequiredDescription
Webhook URLTextYesThe HTTP endpoint to send data to. Must start with http:// or https:// (e.g., https://example.com/webhook)
HTTP MethodSelectNoThe HTTP method to use: POST, PUT, or PATCH. Default: POST

Target Settings

Webhook does not require additional target settings. Data is sent directly to the configured URL.

Supported Operations

Sync Modes: Insert, Upsert

Audience Sync Modes: Add, Remove, Mirror, Upsert

Features

  • Field Mapping: No — the full record is sent as a JSON payload
  • Schema Introspection: No — webhooks accept arbitrary JSON

How It Works

Zeotap sends each batch of rows as a single JSON payload to the configured HTTP endpoint:

  1. Rows are collected into a batch and serialized as a JSON array
  2. An HTTP request is made to the webhook URL using the configured method
  3. The Authorization header is set if an authorization header value is configured
  4. The X-Api-Key header is set if an API key is configured
  5. The Content-Type header is set to application/json

Request Format

Each request body contains the sync mode, and an array of rows with their data, operation, and primary key:

{
  "sync_mode": "insert",
  "rows": [
    {
      "data": {
        "email": "user@example.com",
        "name": "Jane Doe",
        "score": 85
      },
      "operation": "added",
      "primary_key": "user-123"
    }
  ]
}

The operation field reflects the diff status of each row (added, changed, or removed) and is populated for audience syncs using mirror mode. The primary_key field contains the row’s primary key value when available.

Response Handling

  • 2xx responses: Treated as successful delivery
  • Non-2xx responses: Treated as failures; the HTTP status code and response body are reported in the sync log

Troubleshooting

Connection failed

Verify the webhook URL is correct and reachable. Check that the endpoint is running and accepting connections. For internal services, ensure network routing allows traffic from Zeotap.

Authentication failed (401/403)

For Authorization Header auth, verify the Authorization header value is correct and the token or API key has not expired.

For OAuth 2.0 auth, verify the Token URL, Client ID, and Client Secret are correct and that the client is authorized for the requested scopes. Zeotap automatically re-fetches the token once on a 401/403 response; a persistent failure usually means the credentials or scopes are wrong, or the endpoint is validating an audience the token does not carry. Use the destination’s Test Connection action to surface the exact token-endpoint error.

Invalid URL

The webhook URL must start with http:// or https://. Relative URLs and other protocols are not supported.

Endpoint returning 500 errors

Server errors cause Zeotap to retry with exponential backoff. If errors persist, check the endpoint’s logs for the root cause. Ensure the endpoint can handle the JSON payload format.

Timeout

Zeotap has a default request timeout. For slow endpoints, ensure the server responds within the timeout window. Long-running processing should be handled asynchronously by the endpoint.

Last updated on
WebflowZapier