Lets Safe
Events API v2

Receive webhook notifications

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

Open API reference Get started

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. Once Lets Safe receives a successful response, the webhook is not retried.
  • On non-2xx responses or network failures, Lets Safe retries with exponential backoff. A transient network issue may therefore cause the same event to be delivered more than once.
  • Events are delivered at-least-once, so always deduplicate on your side using EventType and Payload .

Reopened references

In some cases Lets Safe support may reopen a completed reference step — for example, to update landlord or employer contact details that were originally entered incorrectly. When a step is reopened and subsequently completed again, the relevant completion webhooks ( applicant/landlord/completed , applicant/employer/completed , applicant/completed , etc.) will be sent again for the same applicant. Your integration should handle receiving a completion event for an applicant that has already been marked as complete. We recommend re-fetching the latest report data via the API when you receive any completion webhook.

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)