Skip to main content

Webhooks

Harvestr webhooks let you receive real-time HTTP notifications when events occur in your workspace. When an event triggers (e.g. a feedback is created, a discovery is updated), Harvestr sends a POST request to your configured endpoint with the event payload.

Prerequisites​

  • A Harvestr workspace with the Webhooks feature enabled
  • A publicly accessible HTTPS endpoint that can receive POST requests

Setup​

  1. In Harvestr, go to Settings > Integrations > Harvestr Webhooks
  2. Click "+ Add a new Webhook to organization"
  3. Enter your endpoint URL in the Request URL field
  4. Click Validate — your endpoint must pass the challenge validation
  5. Optionally provide a Secret token for signature verification
  6. Select the events you want to subscribe to
  7. Click Create

Challenge validation​

Before activating a webhook, Harvestr validates your endpoint with a challenge/response handshake:

  1. Harvestr sends a POST request to your URL with a JSON body: { "challenge": "<random-uuid>" }
  2. The request includes an X-Harvestr-Signature header containing the HMAC-SHA256 signature of the body (using your secret token, or an empty string if none was provided)
  3. Your endpoint must respond with a 2xx status code (200-208) within 5 seconds. The response body is ignored — no need to echo the challenge back. Redirects are not followed.
  4. On success, the result is cached for 1 hour — subsequent validations for the same URL will return immediately

If the challenge fails (non-2xx response, timeout, or network error), the webhook is not activated.

Webhook statuses​

StatusDescription
ACTIVEWebhook is delivering events normally
TOO_MANY_ERRORSAutomatically disabled after repeated delivery failures
BLOCKEDManually disabled

Event delivery​

When an event triggers, Harvestr sends a POST request to your URL:

  • Timeout: 5 seconds
  • Success: any 2xx status code (200-208)
  • Failure: non-2xx response or network error

See the Events reference for the full list of events and their payloads.

See Security for details on HTTP headers and signature verification.