How to Set Up a Custom Webhook Workflow Action

The Custom Webhook workflow action sends real-time HTTP requests to any external URL when a workflow runs. Use it to push contacts into other CRMs, trigger external APIs, or notify internal services without writing integration code.

What Custom Webhook does

When a workflow run reaches the Custom Webhook step, Sparkforge assembles your headers, query parameters, and body — including dynamic values like {{contact.email}} — and sends the request to the URL you configured. It supports GET, POST, PUT, and DELETE.

Why it's useful

• Flexible methods: GET, POST, PUT, DELETE for any API operation.
• Multiple auth types: Bearer token, API key, Basic Auth, OAuth2, or no auth with custom headers.
• Dynamic mapping: Insert contact, opportunity, and custom values into headers, params, or body.
• Reusable patterns: Build once, copy across workflows.
• Logging: Optional response capture and execution logs speed up debugging.

Authentication options

Match the auth type your provider expects. Keep secrets in headers, not query strings, unless the provider requires otherwise.

Bearer token

Add header Authorization: Bearer {{location.api_token}}.

API key

Most providers expect a custom header like X-API-Key: {{location.external_api_key}}. Use a query parameter only if the provider requires it.

Basic Auth

Enter Username and Password in the action's Authorization fields. Sparkforge sends the standard Authorization: Basic ... header.

OAuth2

Configure the token in Global Workflow Settings > OAuth2 / Manage Tokens first, then select it in the action. Best for providers that rotate or refresh tokens.

No Auth + custom header

If a provider expects a bespoke header like X-Signature, choose No auth and add the header manually under Headers.

HTTP methods and request shape

• URL with path params: https://api.example.com/contacts/{{contact.id}}
• GET: Read data. No body — pass filters as query parameters.
• POST: Create resources. Send a JSON body or form data.
• PUT: Update resources. Usually requires an ID in the path plus a JSON body.
• DELETE: Remove resources. Typically uses an ID in the path.
• Content-Type: application/json for JSON bodies, application/x-www-form-urlencoded for form fields.

Event mode (CUSTOM vs POST vs GET)

The Event dropdown controls which fields show up in the action UI.

• Event = CUSTOM: Full control. Method picker, Content-Type, and Raw Body editor. Use this for JSON, PUT, or DELETE.
• Event = POST: Simple key/value Body. No raw body editor. Use for basic form submissions.
• Event = GET: No body. Use Query Parameters to pass filters. Save Response is available here.

The tag icon next to URL, Headers, Query Params, and Body fields opens the dynamic value picker for inserting tokens like {{contact.id}}.

Headers and query parameters

Common header examples:

Authorization: Bearer {{location.api_token}}
Content-Type: application/json
X-API-Key: {{location.external_api_key}}
X-App-Version: 2024-11-01

Common query parameters:

lead_id={{contact.id}}
email={{contact.email}}
source=workflow

Payload examples

Flat JSON for a create call:

{
  "id": "{{contact.id}}",
  "first_name": "{{contact.first_name}}",
  "last_name": "{{contact.last_name}}",
  "email": "{{contact.email}}",
  "phone": "{{contact.phone}}"
}

Nested JSON:

{
  "contact": {
    "id": "{{contact.id}}",
    "name": "{{contact.name}}",
    "phones": ["{{contact.phone}}"],
    "tags": ["{{contact.tag}}", "new-lead"]
  }
}

Form-encoded: set Content-Type to application/x-www-form-urlencoded and provide key/value pairs instead of JSON.

Setup steps

1. Open the workflow under Automation > Workflows.
2. Click + Add action and choose Send Data > Custom Webhook.
3. Give the action a clear name (e.g., "Send Lead to External CRM").
4. Pick the Event mode. CUSTOM exposes Method, Content-Type, and Raw Body. POST and GET use simpler interfaces.
5. Paste the provider URL, including any path variables.
6. Choose Authorization and supply credentials.
7. Add required headers and query parameters.
8. Enable Save Response if available, to capture the provider's reply.
9. Save and trigger a test against a sandbox endpoint like Webhook.site or Postman, then check Execution Logs.

Testing and troubleshooting

Validate before going live. Start with Test Workflow in draft mode using a sample record. Cross-check with provider-side tools and review Execution Logs for status codes.

Common HTTP errors

• 400 / 422: Invalid payload. Match required fields, types, and structure.
• 401 / 403: Bad credentials, wrong auth type, expired token, or missing scopes.
• 404: Wrong path or missing ID. Confirm endpoint and path variables.
• 409: Conflict or idempotency issue. Use unique IDs or follow upsert rules.
• 429: Rate limited. Add delays or stagger calls.
• 5xx: Provider error. Retry and contact provider support.