Skip to main content
The Custom Webhook action lets a workflow send data outward to any third-party service — a CRM, a payment processor, a custom API, a spreadsheet tool, or any other system that accepts HTTP requests. Each time a contact reaches this step, the HoopAI platform fires an HTTP request containing data you specify to the endpoint you configure. Unlike a basic outbound webhook, the Custom Webhook action gives you full control over the request method, headers, authentication, query parameters, and body structure.

​
When to use a custom webhook

Use the Custom Webhook action when you need to:
  • Push contact data to an external database or CRM at a specific point in a workflow
  • Notify a third-party service of a conversion event (e.g., a form submission or payment)
  • Trigger an action in another system (e.g., provision an account, create a record, send a Slack notification)
  • Pass workflow or contact data to a custom application that your team manages
For simpler integrations that don’t require custom authentication or complex request structure, a basic Webhook (Outbound) action may be sufficient.

​
Adding a custom webhook action

  1. Open your workflow in the builder and click the + icon at the point where you want the webhook to fire.
  2. Search for or select Custom Webhook from the action list.
  3. Configure the request using the settings described below.
  4. Save the action and test it before publishing.

​
HTTP method

Choose the HTTP method that matches the operation your external API expects:
MethodWhen to use
GETRetrieve data using query parameters; no request body
POSTSend data to create a new resource; uses a request body
PUTUpdate an existing resource; uses an ID and request body
DELETERemove a resource, typically by ID in the URL path
POST is the most common method for sending contact data to external services.

​
Webhook URL

Enter the full URL of the external endpoint that will receive the request. This URL is provided by the third-party service you are integrating with. Make sure the URL is correct and the endpoint is accessible from the internet.

​
Authentication

Choose the authentication method required by your external API:
  • No auth — the endpoint is public or uses custom header-based authentication
  • Bearer token — adds an Authorization: Bearer <token> header automatically
  • API key — adds a custom header with your API key (you specify the header name and value)
  • Basic auth — sends a Base64-encoded username and password pair in the Authorization header
  • OAuth 2.0 — uses a pre-configured OAuth token stored in your workflow global settings
Store sensitive credentials (tokens, API keys) in the authentication fields rather than hardcoding them into the URL or body. This is both more secure and easier to update when credentials rotate.

​
Headers

Headers provide metadata about the request. Common headers include:
  • Content-Type: application/json — required by most APIs that accept JSON payloads
  • X-API-Key: your_key_here — a common pattern for key-based authentication
  • Cache control and rate-limit headers as required by the destination API
Click Add Header to add as many headers as the destination requires. Header values support dynamic values from the contact record.

​
Query parameters

For GET requests, query parameters are the primary way to pass data. For POST and PUT requests, you may still include query parameters for filtering or routing purposes alongside a request body. Click Add Parameter to add key-value pairs. Parameter values support dynamic variables.

​
Request body

For POST and PUT requests, the request body contains the data payload. The Custom Webhook action supports building a JSON body using:
  • Static values — fixed text you type directly
  • Dynamic contact fields — values pulled from the contact’s record at the moment the action runs
A simple example that sends contact data: 
{
  "first_name": "{{contact.first_name}}",
  "last_name": "{{contact.last_name}}",
  "email": "{{contact.email}}",
  "phone": "{{contact.phone}}",
  "tags": "{{contact.tags}}"
}
You can nest objects and arrays within the body to match whatever structure the external API requires.

​
Using dynamic values

Dynamic values let you populate the request with live contact data rather than static placeholders. Available variables include:
  • Contact fields: {{contact.email}}, {{contact.first_name}}, {{contact.phone}}, custom fields, etc.
  • Opportunity data: pipeline name, stage, value
  • Workflow variables passed from earlier steps

​
Testing the webhook

Before publishing your workflow, verify the webhook is firing correctly:
  1. Use the Test Workflow button in draft mode with a real contact record.
  2. Direct your webhook URL to a tool like Webhook.site or Postman to capture the raw request and inspect the headers, parameters, and body.
  3. Confirm the data structure matches what the destination API expects.
  4. Review the Execution Logs after the test to check the response status code and any error messages.
A 2xx status code in the logs confirms the external system accepted the request. A 4xx code typically indicates an authentication or payload format issue. A 5xx code suggests a problem on the receiving server.
If the destination API returns data in its response (such as a created record ID), that response data is recorded in the execution logs but is not automatically mapped back into the contact record. Use the platform’s API or a separate integration if you need to write response data back to a contact.

​
FAQs

There is no enforced limit on the number of Custom Webhook actions in a workflow. You can fire webhooks to multiple endpoints at different stages of the automation.
The execution logs record the failure with the HTTP status code and any error message returned by the server. The workflow continues to the next step regardless of the webhook response. If your use case requires retry logic, add error handling steps using If/Else conditions to check for failure and re-attempt or notify your team.
No. The HoopAI platform sends requests from its servers to the specified URL. Localhost addresses and private network URLs are not reachable. The endpoint must be publicly accessible.
They serve a similar purpose but differ in configurability. Custom Webhook supports multiple HTTP methods, full authentication options, custom headers, and a flexible body builder. The basic Webhook (Outbound) action is simpler and follows a more fixed request format. Use Custom Webhook for integrations that require specific request structures.
Last modified on March 5, 2026