> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firsttouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For API operations, fetch https://gateway.firsttouch.ai/api/public/openapi.json for the complete input/output schemas, internal references, and x-mcp-annotations. Endpoint Markdown intentionally omits generated schema fragments. Select /api/public/tools/<tool_name> using the exact underscore-separated name. Send requests to https://gateway.firsttouch.ai; the canonical document currently omits servers. Start at https://docs.firsttouch.com/api-reference/agent-start.md.

# Webhook Troubleshooting

> Resolve missing webhook events, rejected URLs, signature failures, retries, and delivery-history questions.

Start with **Team Settings > Integrations > Webhooks > Settings > Delivery history**. Open the affected delivery to inspect **Event data**, its IDs, and each attempt's HTTP status, timing, error, and available app response.

## Why Can't I See Webhooks?

Check that you selected the correct Team, are its owner or an Admin, and that Webhooks is enabled for your environment. A missing card does not by itself mean your receiving app is misconfigured.

If **Your webhook access has changed** appears, use **Check access again** after an owner verifies your permissions. If your role is correct but the feature is unavailable, contact FirstTouch support to confirm availability.

## Why Is My URL Rejected?

Use the final public HTTPS URL provided by your receiver. Confirm:

* It uses port 443, not HTTP or a custom port such as 8443.
* It uses a DNS hostname, not an IP address.
* It has no embedded username/password or `#fragment`.
* It is no longer than 2,048 characters.
* Its DNS records resolve only to public addresses, not localhost or private/special-use networks.

FirstTouch does not follow redirects. A saved URL can still fail at delivery time if its DNS, certificate, or network access is invalid. For local development, use a secure, publicly reachable HTTPS receiver rather than a localhost URL.

## Why Is Send Test Event Unavailable?

Open the destination's **Overview** and turn on **Send events to this destination**. Use **Edit destination** to select at least one event, then choose one in **Testing**.

Wait for any save operation to finish. A test also needs an active signing secret: if all secrets were revoked, use **Create secret**, configure the receiver, and try again.

Only subscribed events appear in the test selector. Copying or viewing **Example data** does not send a request.

## Why Did A Test Work But No Real Event Arrive?

Testing proves the receiver can accept that synthetic request, not that a real business event occurred.

1. Confirm the correct Team, destination URL, enabled state, and exact event subscription.
2. Check that the real action completed. Queued or failed outreach is not a sent event.
3. For replies, confirm the conversation is tracked by FirstTouch. See [event scope](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md#event-scope).
4. For signals, confirm the source feature is configured and a supported signal was actually detected. See [Social Engagement](https://docs.firsttouch.com/WebApp/Signals/Social-Engagement.md) or [Website Visitors](https://docs.firsttouch.com/WebApp/Signals/Website-Visitors.md).
5. Clear history filters, check the date range, and click **Refresh**. Search by event or delivery ID when available.

Events are routed to enabled, subscribed destinations when FirstTouch records them for delivery. New destinations do not automatically receive older events, and events recorded while a destination is off are not backfilled when it is turned on.

## Why Are Some Replies Or Imported Messages Missing?

Received events are not a full export of connected inboxes. They apply to conversations tracked by FirstTouch. Initial LinkedIn history imports are excluded from live reply events, and LinkedIn replies need reliable single-contact attribution.

Subscribe separately to `linkedin.message.received` and `linkedin.inmail.received` if you need both categories. Do not infer the category solely from a message subject. See the [event catalogue](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md#event-catalogue).

## Why Is A Payload Field Null Or Missing?

First check the event type and **Testing > Example data > Fields**. Not all sources supply the same information.

* An event may not be linked to a Flow Plan, action, or enrollment.
* Contact enrichment and HubSpot links may be unavailable or unmatched.
* A website signal may identify a company but not a person.
* Message IDs, subjects, content formats, recipient lists, and attachment metadata depend on the source.
* Content fields are omitted for a destination whose sensitive-data setting is disabled. The current settings form does not expose a separate switch for that setting.

Handle nulls and absent optional fields. Historical delivery payloads are snapshots; enriching a contact later does not change them. Attachment links can expire independently of the delivery history. See [business data](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md#business-data).

## Why Does Signature Verification Fail?

Check that your receiver:

* Uses the correct destination's active signing secret, including its `whsec_` prefix, as a UTF-8 key—not a Base64-decoded key.
* Verifies the original raw request bytes before JSON parsing or reserialisation.
* Signs the exact timestamp header, a `.`, and those raw bytes with HMAC-SHA256.
* Parses the `key_id:v1=digest` entries in `X-FT-Webhook-Signature`, including comma-separated entries during rotation.
* Uses constant-time digest comparison and a synchronised clock for its own timestamp-tolerance policy.

If you replaced the secret immediately, the old one stopped working immediately. For normal rotation, update the receiver before the old secret expires, within at most one hour. An eligible active secret can be revealed again in **Overview > Signing secret**; expired or revoked secrets cannot.

Use the [verification example](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md#signature-verification). Never send signing secrets to support.

## Why Am I Receiving Duplicate Events?

FirstTouch retries unsuccessful or unconfirmed deliveries. Your app may have processed a request before the response was lost, and **Resend** can deliver the same event again.

Deduplicate with the payload's `idempotency_key` or `X-FT-Webhook-Id`. Attempt IDs and a resend's delivery history row ID are different identities and must not be your only deduplication key. Durably record acceptance, return `2xx` for duplicates, and avoid repeating downstream side effects. See [duplicate handling](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md#duplicate-handling).

## What Do Pending, Processing, Failed, And Canceled Mean?

| Status | What to check |
| - | - |
| **Pending** | The delivery is waiting, including retry backoff or a temporary timeout pause. Inspect previous attempts before assuming nothing happened. |
| **Processing** | An attempt is running. Wait, refresh history, or use **Check status** if offered in the details drawer. |
| **Delivered** | The receiver returned `2xx`. Investigate the receiving app if its downstream action did not complete. |
| **Failed** | All eight attempts were unsuccessful. Fix the receiver, then use **Resend** if available. |
| **Canceled** | The destination was turned off or deleted, or sending was otherwise canceled. Turning it on does not automatically revive the delivery. |

Retries normally span approximately 24 hours, with jitter and possible additional scheduling delays. Five consecutive timeouts without a response cause a one-hour pause. For exact intervals, see [retries and resends](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md#retries-and-resends).

## How Do I Fix HTTP And Network Failures?

Open **Delivery details** and inspect each attempt. These are receiver-side diagnostics, not proof of one specific root cause.

| Result | Checks and resolution |
| - | - |
| `3xx` | Replace the URL with the final HTTPS receiver URL. Redirects are not followed. |
| `401` or `403` | Check receiver permissions, signature verification, and access rules. There is no custom-header field in FirstTouch's destination form. |
| `404` | Verify the path and that the receiver is deployed at that URL. Lowering request rates does not fix an incorrect path. |
| `429` | Inspect your receiver's capacity and rate limits; use durable queuing and a prompt acknowledgement. FirstTouch uses its own retry schedule, not `Retry-After`. |
| `5xx` | Check the receiving app's availability and logs, then confirm with a test. |
| **No response** / `timeout` | Ensure DNS, TLS, firewall rules, and the receiver allow a response within five seconds. Move slow work out of the request handler. |
| `connection_failed` | Check public DNS resolution, certificate validity, and network reachability. Mixed public/private DNS results are rejected. |
| `no_active_key` | Create a signing secret, store it in the receiver, and test again. |

Non-`2xx` responses, including `4xx`, remain eligible for automatic retries until the attempt budget is exhausted. After fixing the issue, test the destination; resend a completed delivery only when appropriate for your receiver's duplicate handling.

## Why Is Resend Unavailable?

**Resend** is offered only when the delivery is no longer pending or processing and the destination still exists, is enabled, and has an active signing secret. The delivery must also be within the 30-day history window.

If a destination was turned off, turn it on and restore a signing secret if needed. A deleted destination cannot resend its former deliveries. Resend is an individual-delivery action, not bulk recovery or a backfill of events that were never routed to the destination.

If an edit or secret change reports an in-flight delivery or a busy operation, wait briefly, refresh, and retry. If another administrator changed the destination, reload its current settings before saving again.

## Why Is The App Response Shortened Or Redacted?

FirstTouch retains only bounded response diagnostics, not a complete receiver response or its headers. Response content is limited to 4,096 bytes before sanitisation and may have credentials redacted or unsafe diagnostic text omitted. A response-body read failure can appear even when `2xx` response headers already established delivery success.

Use your receiver's own logs for full diagnostics. Do not deliberately echo secrets into response bodies.

## Why Can't I Find Older Deliveries?

History, payloads, and attempts are available for **30 days from delivery creation**. Changing filters cannot recover older deliveries. Store any longer-term audit trail in your own receiving system.

## What Should I Send To Support?

Include the affected Team and destination name, event type, event ID, delivery ID, approximate UTC time, visible status, and a sanitised error or HTTP status. Describe the expected result and whether a synthetic test works.

Do not include signing secrets, authentication credentials, full customer message bodies, or unsanitised response content. If screenshots are needed, redact personal data and secret values first.

For setup steps, return to [Configure Webhooks](https://docs.firsttouch.com/WebApp/Webhooks/overview.md). For the contract and limits, see the [technical reference](https://docs.firsttouch.com/WebApp/Webhooks/technical-reference.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.