Webhook Events

What Webhook Events covers

Webhook Events in the current OrcaPulse project are more than a single endpoint. The app supports both inbound receive webhooks and outbound send webhooks, and it also uses a workflow step type to deliver webhook payloads during lead execution.

That makes webhook integrations one of the clearest system-to-system bridges in the current codebase.

Receive webhooks and lead creation

OrcaPulse can generate a unique public webhook URL for a user and store it as a receive webhook integration. Incoming payloads are accepted at a tokenized endpoint, mapped into lead fields, validated, and then turned into real lead records in the database.

The receive path is designed for universal lead capture from external sources that can POST data into OrcaPulse.

• Generated receive URL: the backend creates a unique token-based webhook URL per user.
• Field mapping: incoming payloads can be mapped from nested source paths into target fields like name, email, and phone.
• Lead creation: valid webhook payloads create lead records with source `WEBHOOK` and store the raw payload in metadata.
• Minimum validation: the receive flow requires at least an email or phone number before a lead is created.

Send webhooks and outbound delivery

The project also stores outbound send webhook integrations. These are separate from receive webhooks and are meant for pushing lead or workflow data out to external systems.

Send webhook records include the destination URL, optional authorization header, a display name, counters for how many webhooks were sent, and timestamps for the last send.

• Separate integration type: send webhooks are stored independently from receive-mode integrations.
• URL validation: outbound webhook URLs are checked for valid format before being saved.
• Optional auth header: the send integration can store an authorization header for downstream systems.
• Send counters: outbound webhooks track send counts and last-sent time in integration config.

Workflow webhook sync step

Webhook delivery is a real workflow step type in the backend execution engine. When a workflow reaches a webhook step, OrcaPulse builds a payload from lead and workflow data, applies custom field templating, sends the HTTP request, and records timeline events for pending, success, or failure states.

The workflow builder already exposes this configuration in the UI, including webhook selection, direction awareness, and custom payload fields using placeholders such as`{{name}}`, `{{email}}`, `{{phone}}`, and `{{status}}`.

• Step type support: `webhook_sync` is a concrete workflow action, not a placeholder label.
• Payload templating: default and custom fields can be assembled from lead data placeholders.
• HTTP delivery: the workflow executor sends JSON to the configured webhook URL with an Orca user agent.
• Timeline logging: send attempts and failures are visible in lead timeline events.

Testing and configuration patterns

The webhook integration controller already includes test paths for both directions. Receive webhooks can be simulated to preview extracted fields based on the current mapping, and send webhooks can be tested against the configured destination URL with a sample payload.

This makes webhooks easier to set up incrementally because teams can validate the integration before relying on it inside a production workflow.

• Receive simulation: teams can test how mapped fields will be extracted from sample incoming payloads.
• Send simulation: outbound webhook integrations can be tested with sample lead data before production use.
• Builder guidance: the workflow builder clearly distinguishes receive and send webhook modes during selection.

Visibility and stats

Webhook integrations in the current project track operational counts. Receive integrations store webhook receive counts, leads created, and the last webhook time. Send integrations track how many outbound webhooks were sent and when the last delivery happened.

That means the webhook layer is not only transport logic. It also gives operators enough information to understand whether integrations are active and being used.

• Receive stats: counts include inbound webhooks received and leads created from them.
• Send stats: counts include outbound webhook deliveries and last-sent timestamps.
• Lead metadata: inbound lead records preserve the original webhook payload for later inspection.

Next steps

After Webhook Events, the next useful integration page is usually API Reference or Automation Connectors, depending on whether you want to document direct endpoints or higher-level connected tools next.