Receive updates from Letted

A webhook sends a small message from Letted to another system when an event happens. You might use one to update a tracker when an agreement is completed or a maintenance task changes status.

Events can come from changes made through the API, Letted's interface or background processes. They are not limited to changes your connection made.

Set up a destination

Your other system needs to provide a public HTTPS address that can receive these messages and verify their signature. Ask its provider for a webhook receiving URL; this is not usually the normal address you use to sign in.

1. Open Settings → Integrations and choose Webhooks.
2. Choose New webhook.
3. Select an API key with view permission for the records you want updates about.
4. Enter the receiving URL and choose the events.
5. Save and copy the signing secret into the receiver's secure settings.
6. Use Send test, then check the receiving system accepted it.

The API key controls which properties and event types are available. Agreement and tenancy events need tenancies:read; tenant events need tenants:read; task events need tasks:read.

The signing secret is separate from your API key. It helps the receiver check that a message really came from Letted. Keep both private.

Available events

• tenancy.created: a tenancy was saved.
• tenancy.updated: tenancy details or tenant membership changed.
• tenancy.status_changed: its date-based status changed; includes previousStatus and status.
• tenant.updated: tenant details or portal access changed.
• tenant.invitation_sent: the email provider accepted an invitation.
• agreement.sent: an agreement was sent for signature.
• agreement.tenant_signed: an individual tenant signed; includes signerId, signedAt and version.
• agreement.completed: all required signatures are complete, or an unsigned form has been completed. Read GET /api/v1/agreements/{id} and check signatureRequired and status: signed agreements are fully_signed; unsigned forms are completed.
• task.created: a task was saved; includes category and status.
• task.status_changed: a task changed status; includes category, previousStatus and status.

A connection test uses integration.test. It confirms the receiving route, not a real tenancy or task change.

Tenancy statuses Future, Ongoing and Expired follow the tenancy dates. They do not confirm a physical move-in or move-out. There are no rent-late, notice-received or documents-complete events in this release.

Example event

This is an illustrative task.status_changed message. IDs and dates below are fictional.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "type": "task.status_changed",
  "apiVersion": "v1",
  "createdAt": "2027-02-10T14:30:00.000Z",
  "data": {
    "propertyId": "11111111-1111-4111-8111-111111111111",
    "resourceId": "44444444-4444-4444-8444-444444444444",
    "category": "Maintenance",
    "previousStatus": "In Progress",
    "status": "Completed"
  }
}

Real record events identify the affected record with data.resourceId and its property with data.propertyId. Agreement events also include tenancyId. The test message instead contains data.message.

For your provider: task events use stored status labels, including In Progress, Waiting Tenant and Waiting Contractor. Task lookup responses use InProgress, WaitingTenant and WaitingContractor. Account for that difference when comparing them. Fetch the latest record if you need its current state.

Allow for repeats and delays

The receiver should save the event ID and avoid processing the same event twice. Events can arrive more than once or out of order. A message describes a change; it is not a guarantee that the record is still in that state.

Letted retries unsuccessful deliveries, up to eight attempts, with increasing delays. Respond with a 2xx status once the event is safely accepted. The delivery timeout is ten seconds, so lengthy work should run after acceptance.

If updates are missing, check the receiving system's logs and contact support with the event ID if available. There is currently no delivery-history or manual-retry control on the Integrations page.

Edit or stop updates

Use Disable to stop a destination. Revoking its key or losing paid-plan eligibility also prevents deliveries.

Saving an edited webhook replaces its signing secret and cancels outstanding deliveries for that destination. Update the receiving system with the new secret at the same time.

Notes for the person connecting your software

The destination must use HTTPS on port 443 and resolve to public internet addresses. Local/private addresses, embedded username/password credentials, URL fragments and redirects are not supported.

Messages have these headers:

Content-Type: application/json
X-Letted-Event-Id: EVENT_ID
X-Letted-Timestamp: UNIX_TIMESTAMP_IN_SECONDS
X-Letted-Signature: v1=HEX_SIGNATURE

Verify the signature as HMAC-SHA256 using the signing secret and this exact input:

EVENT_ID.TIMESTAMP.RAW_REQUEST_BODY

Use the original body bytes before parsing JSON, not re-serialised JSON. Compare signatures in constant time, check the timestamp against a short tolerance suitable for your receiver, and deduplicate using the event ID. Letted signs each delivery attempt with its delivery timestamp.

A useful prompt

Read these Letted guides first:
https://app.letted.com/docs/receiving-events
https://app.letted.com/docs/property-tasks
https://app.letted.com/docs/api-reference

If you cannot open them, ask me to paste the pages rather than guessing.

Using this Letted webhook guide, help my provider design a receiver that
updates [my tracker] when a Maintenance task changes status. Explain the
setup in plain English, then give the technical checklist. Include
signature verification, event-ID deduplication, out-of-order delivery and
fetching the current task. Do not assume my tracker has a built-in connector.