DestinationsOtherWebhook

Webhook

Send data to any HTTP endpoint. Use SignalSmith 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 SignalSmith
  • An authorization header value or API key (if the endpoint requires authentication)

Authentication

Webhook uses Authorization Header authentication. 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 request (optional, for endpoints that use API key authentication)

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

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

SignalSmith sends each row (or batch of rows) as a JSON payload to the configured HTTP endpoint:

  1. Each row is serialized as a JSON object
  2. An HTTP request is made to the webhook URL using the configured method
  3. The Authorization header is set if configured
  4. The Content-Type header is set to application/json
  5. SignalSmith retries failed requests with exponential backoff

Request Format

Each request body contains a JSON payload with the row data:

{
  "data": {
    "email": "user@example.com",
    "name": "Jane Doe",
    "score": 85
  },
  "metadata": {
    "sync_id": "sync_abc123",
    "sync_mode": "insert",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Response Handling

  • 2xx responses: Treated as successful delivery
  • 4xx responses: Treated as permanent failures (the record is marked as failed)
  • 5xx responses: Treated as transient failures (the request is retried)

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 SignalSmith.

Authentication failed (401/403)

Verify the Authorization header value is correct. Ensure the token or API key has not expired. Check the endpoint’s authentication requirements.

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 SignalSmith 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

SignalSmith 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.

SlackOverview