Configure webhooks

Send Fetchply events as signed JSON POST requests to your endpoint, verify their signatures, and diagnose delivery failures.

Webhooks send events from your agent to your own systems as JSON POST requests. Each agent supports up to 10 endpoints.

Add an endpoint

Open Integrations → Webhooks, choose a descriptive name, and enter a public HTTPS URL. When the endpoint is created you are shown its signing secret exactly once; copy it and store it like a password.

Select events

Choose from new_message, new_conversation, new_lead, feedback_received, training_completed, training_failed, and handoff_requested.

Verify signatures

Every delivery includes an X-Fetchply-Signature header in the form t=<timestamp>,v1=<signature>. Compute an HMAC SHA-256 of <timestamp>.<raw request body> with your signing secret and compare it to v1. Reject requests whose signature does not match or whose timestamp is older than a few minutes.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
  if (!match) return false;
  const [, timestamp, signature] = match;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Test delivery

Send a test from the endpoint's row and inspect the JSON at your receiver. Respond with a 2xx status within 10 seconds; anything you need to do with the payload should happen after you respond.

Activate and monitor

Only active endpoints receive events. Pause an endpoint to stop delivery without deleting its configuration.

Delivery and retries

If your endpoint is unreachable, times out, or responds with a 5xx or 429 status, Fetchply retries the delivery automatically with increasing delays for up to 6 attempts. Other 4xx responses are treated as your receiver rejecting the event and are not retried. Each delivery carries a unique X-Fetchply-Delivery header; process repeated deliveries idempotently by tracking that ID, since retries can occasionally deliver the same event twice.

Localhost, private IPs, non-HTTPS destinations, and endpoints that respond with a redirect are rejected. Always verify the signature at your receiver so you know a request really came from Fetchply.

Troubleshooting

My endpoint receives nothing. Confirm the endpoint is active, the event you expect is selected, and the URL is a public HTTPS address. Use the test button to check reachability.
The test fails with "not a public HTTPS endpoint". Tunnels to a local machine, private network addresses, and plain HTTP URLs are blocked. Host the receiver on a public HTTPS URL.
Signature verification fails. Make sure you compute the HMAC over the raw, unmodified request body (not a re-serialized version) and that you are using the current secret; rotating the secret invalidates the old one immediately.
An endpoint shows "Unsigned". It was created before signing existed. Use the key button on its row to generate a secret; deliveries are signed from that moment on.
I received the same event twice. That is expected on rare occasions after a retry; deduplicate using the X-Fetchply-Delivery header.

Use the sample payloads shown in the dashboard as the current shape. Make receivers tolerant of new optional fields.