Webhook setup

Use callbacks as the primary way to receive screening progress and completion. Follow the status meanings and flow for your organization’s configuration:

• With Analyst Assistance — processing and analyst review, including Redressing and Redressed.
• Without Analyst Assistance — processing and completion without analyst-review stages.

Register your callback

Use POST /api/ApiClient/updateWebHook with your private API key. The request body is a JSON string containing your callback URL, not a JSON object.

curl --fail -sS -X POST https://api.ferretly.com/api/ApiClient/updateWebHook \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"https://example.com/hooks/ferretly"'

This changes the API client’s callback setting. Verify the saved statusUpdateCallbackUrl through GET /api/ApiClient.

Receive a GET request

Ferretly calls the URL with HTTP GET, adding three URL-encoded query parameters. There is no JSON event body.

GET /hooks/ferretly?subjectId=11111111-1111-4111-8111-111111111111&status=Complete&externalSystemId=candidate-001 HTTP/1.1
Host: example.com

Parameter	Meaning
subjectId	Ferretly subject UUID
status	Screening or review event from BackgroundCheckStatus; see your workflow’s status guide
externalSystemId	Identifier supplied when creating the subject; empty when none was supplied

An existing callback query string is preserved; Ferretly appends its parameters with &. Do not register your own query parameters with the same three names.

Acknowledge and process

Return a successful 2xx response promptly. Queue longer work in your application and retrieve results after the completion notification.

Use the status supplied by the webhook. Rechecking that status after every notification is unnecessary. Make processing idempotent: notifications do not contain an event ID or run ID, and delivery should not be treated as exactly once or strictly ordered. In the Analyst Assistance flow, handle Redressed and Complete without duplicating the completion action.

Retry policy

Delivery retries and their timing can change without notice and may vary by organization. Do not depend on a fixed retry count, schedule or specific set of retried response codes. Keep your receiver available, acknowledge accepted notifications promptly, and contact Ferretly Integrations if an expected update is missing.

Verify notifications

Use HTTPS. Ferretly does not currently send an Authorization header or cryptographic signature with these callbacks. Your Ferretly API key authenticates requests you make to Ferretly; it is not sent to your receiver.

Customers can use a dedicated, unpredictable token in the callback URL or restrict incoming requests to Ferretly’s sending IP addresses. Request the current IP address list and coordinate your receiver configuration with Ferretly Integrations. Keep callback tokens out of logs and support messages, and never put your Ferretly API key in the callback URL.

Planned identity-resolution webhook

Not part of the current callback contract

Ferretly plans an additional webhook for identity-resolution events, such as a profile being found, agentic search completing, and an analyst marking profiles reviewed. Confirm release availability and the event contract with Ferretly before implementing it. The current callback registration and three parameters above document screening-status notifications.

API reference

See Set the webhook URL for registration details. The OpenAPI specification includes the current screening-status callback definition.