Skip to content

Send events to your own systems with webhooks

A webhook tells another system the moment something happens in LintelCRM, for example a new lead or a payment received. You give LintelCRM an address on your side. When a chosen event happens, LintelCRM sends a signed message to that address. Webhooks are part of the Professional plan and above. The page says “Send real-time CRM events to your own endpoints over HTTPS.”

What you can do depends on your plan.

  • Starter: webhooks are locked. The page shows “Pro feature” and an upgrade button.
  • Professional: up to 3 active webhooks, with up to 5 events each. Only five events are available: property.created, tenancy.created, payment.received, maintenance.reported and compliance.expiring_soon. The page shows how many you have used. At 3 you see “Pro plan limited to 3 active webhooks.” Pause or delete one to add another.
  • Business and Enterprise: unlimited webhooks, every event, and no limit on events per webhook.

If you downgrade, events your plan no longer includes stop being sent at once. See Billing and your plan.

You need permission to add webhooks. Owners and admins have it. Someone with only webhook view access can see the list, but the endpoint addresses are masked.

  1. Open Settings and choose Webhooks, then select New webhook. The first time, select Create your first webhook.
  2. Under Endpoint, enter the address LintelCRM should post to. It must start with https://. A plain http address is refused: “Must use https:// — plaintext http endpoints aren’t allowed.” An address that points at a private or internal network is refused too.
  3. Under Events, tick the events you want. You can search by name. You must pick at least one: “Select at least one event.”
  4. Select Create webhook.
  5. The next window, Save your signing secret, shows the secret once. Copy it and store it safely, then tick “I’ve saved this secret somewhere safe”. The window cannot be closed until you copy the secret or tick that box.

Your developer uses the secret to check that each message really came from LintelCRM. It cannot be shown again. If you lose it, rotate it.

Events are named after the thing and what happened, such as property.status_changed or deposit.protected. They cover:

  • Properties, including landlord assigned or unassigned.
  • Tenancy applications, tenancies, renewals and terminations.
  • Payments received or failed.
  • Deposits: held, protected, returned in full or part, or disputed.
  • Compliance documents: created, renewed, expiring soon and expired.
  • Maintenance jobs and inspections.
  • Viewings.
  • Offers and sales: agreed, exchanged, completed, fell through.
  • Leads: lead.captured when an enquiry arrives, and lead.converted when a lettings lead is converted to an applicant. See Leads and the enquiry form.

Each message is a JSON body with event, event_id, business_uuid, occurred_at and data. The data fields depend on the event. Property events also carry an external_ref, your own reference for the property if it was imported. The Webhook integration guide (at /settings/webhooks/docs, reached from the Delivery log link “Read the integration guide”) has the full event list and code samples.

Every message is signed so your system can trust it. LintelCRM sends these headers: X-Webhook-Event, X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature and Webhook-Signature.

  1. Take the timestamp from X-Webhook-Timestamp and the raw request body.
  2. Work out an HMAC-SHA256 of the timestamp, a full stop, then the body, using your signing secret.
  3. Compare it with X-Webhook-Signature, which is sha256= followed by the hex result.
  4. Reject the message if the timestamp is more than 5 minutes (300 seconds) from your server’s clock. This stops someone replaying an old message.
  5. Use X-Webhook-Delivery to ignore a message you have already handled. Delivery is at least once, so the same message can arrive twice.

Webhook-Signature is a newer header that looks like t=<timestamp>,v1=<signature>. It signs the timestamp, the delivery ID and the body, and it carries two signatures while you rotate a secret.

A test sends a made-up event to your endpoint, so you can check it is reachable and verifies signatures. You need permission to manage the webhook.

  1. On the Webhooks list, open the row menu and choose Send test event, or open the webhook and choose it there.
  2. Select Send test event to confirm. LintelCRM sends a sample of the first event the webhook subscribes to. You see “Test event queued. Check the delivery log in ~30 seconds.”
  3. Open the webhook and look in Delivery log. The test has a TEST badge.

A test is sent once. It is never retried, it does not raise a failure alert, and it does not change the webhook’s health. It works on a paused webhook too, so you can check the endpoint before you resume.

Open a webhook from the list to see its page. Configuration shows the endpoint, the subscribed events and the date created. Cards show Total deliveries, Success rate, Last triggered and Failure streak. The Delivery log lists each message with a status:

  • Pending: waiting to be sent or to be retried.
  • Delivered: your endpoint answered with a 2xx status.
  • Failed: an attempt failed and another is booked.
  • Abandoned: every attempt failed. LintelCRM stopped trying.

You can filter by status, event and date, and open a row to see the response code and the start of your endpoint’s reply. The list shows the last 7 days on Professional and the last 30 days on Business and Enterprise. A webhook is shown as Active, Paused or Failing.

A delivery counts as delivered only when your endpoint answers with a 2xx status within 10 seconds. Any other answer, a timeout or a connection error is a failure. A redirect is never followed and counts as a failure. LintelCRM tries up to 7 times. After a failed attempt it waits:

  1. 5 seconds, then
  2. 1 minute, then
  3. 5 minutes, then
  4. 30 minutes, then
  5. 6 hours, then
  6. 24 hours, then makes the 7th and final attempt.

If the 7th attempt fails the delivery is Abandoned and that message is not sent again. The people who manage the webhook get an email with the endpoint, the event type and the latest response codes. The email is not sent for every failure, so you are not flooded. After 50 failed attempts in a row LintelCRM turns the webhook off and emails the same people. Fix your endpoint, then choose Resume on the webhook.

Use the row menu on the Webhooks list, or the buttons on the webhook’s page. You need permission to manage the webhook.

  • Edit: change the address or the events, then select Save changes (“Webhook updated.”).
  • Pause: stops sending real events, and cancels messages still waiting to be sent. Choose Resume to start again. On Professional, resuming counts towards the limit of 3 active webhooks.
  • Rotate secret: creates a new signing secret and shows it once. Your old secret stops being the main one at once. For the next 24 hours the Webhook-Signature header carries signatures for both the new and the old secret, while X-Webhook-Signature uses the new secret straight away. Update your receiver before the 24 hours end.
  • Delete: removes the webhook. Messages still waiting for it are cancelled.

Rotate the secret if you think it has been seen by someone it should not have. The rotation window says: “Any requests arriving between rotation and your receiver update will fail signature verification.”

  • Your endpoint is down. Messages are retried 7 times over about a day, then marked Abandoned. The webhook shows Failing. When your endpoint is back, new events are delivered normally. The app has no button to resend an abandoned message.
  • Your endpoint keeps failing. After 50 failed attempts in a row the webhook is turned off and you get an email. Nothing more is sent until you resume it.
  • You pause a webhook. Real events are not sent until you resume it, and messages still waiting for it are cancelled. Do not rely on a resumed webhook to catch up on what it missed.
  • You lose the signing secret. It cannot be shown again. Rotate it to get a new one, then update your receiver.
  • You lose access to the secret after a fault. If the secret cannot be read on our side, attempts fail with “Not sent: the webhook secret cannot be decrypted. Rotate the secret to resume deliveries.” Rotate the secret.
  • You pick an event your plan does not include. You see “Your plan does not allow this webhook configuration. Upgrade to continue.” On Professional, more than 5 events is refused: “Pro plan limited to 5 events per webhook. Upgrade to Business.”
  • Your plan goes below Professional. Webhooks stop sending. See Billing and your plan to upgrade.