Events API v2

Receive webhook notifications

Listen for applicant updates (created, completed, deleted) so your platform stays in sync without polling.

Webhook setup

Configure your webhook URL in the portal Settings so Lets Safe can notify your system as events occur. Events are delivered asynchronously and retried on transient failures.

Where to configure

In the portal, go to


  Settings

and fill in


  Events Webhook Url

. Use an


  https

endpoint you control.

Payload shape

All webhook requests are HTTP POST with a JSON body containing the agent ID, an event type, and a payload. For applicant events, the payload is the applicant UUID. For payment/created, the payload may be an empty string.

Example webhook payload

JSON/HTTP

{
  "AgentId": 123,
  "EventType": "applicant/completed",
  "Payload": "987fcdeb-51a2-43d1-b789-123456789abc"
}

Event types

You may receive these event types (depending on the product and workflow):

applicant/created
applicant/gtor/created
applicant/details/completed
applicant/landlord/completed
applicant/previouslandlord/completed
applicant/employer/completed
applicant/futureemployer/completed
applicant/completed
applicant/deleted
payment/created

Security note

Treat webhook bodies as untrusted input. Always validate the event and re-fetch data via the API using your own API key.

Handling & retries

Respond with any 2xx status code to acknowledge receipt.
On non-2xx responses or network failures, Lets Safe retries with backoff.
Events are delivered at-least-once, so deduplicate on your side.

Recommended handler logic

JSON/HTTP

1. Receive POST from Lets Safe
2. Validate JSON schema + expected AgentId
3. If EventType == applicant/completed:
     - GET /api/v2/applicants/{id}
     - GET /api/v2/applicants/{id}/pdf
     - Attach report to your case/workflow
4. Return 200 quickly (do work asynchronously in your system)