In this section · 4 articles

How Webhook Engine works

Webhook Engine tells other systems when something happens in your Laramin, such as a new user or a published article. It sends a signed message to each address you set up, retries when it fails, and logs every attempt.

Applies to
Webhook Engine 2.2 and later
Who can do this
Platform owner, Administrator, Developer
On this page

In short

A webhook is a message your Laramin sends to another system the moment something happens, so that system doesn't have to keep asking. Webhook Engine sends these messages. You tell it where to send them (a destination) and which events each destination wants. For every matching event, it sends one POST request with a JSON body, signs it so the receiver can check it came from your Laramin, and records what happened in the delivery log.

Webhook Engine only sends. It doesn't receive webhooks from other services. Payment providers and SMS providers that call your Laramin are set up in their own add-ons.

How it works

The parts

PartWhat it isWhere you manage it
DestinationAn address that receives deliveries, with the events it wants, optional filters and extra headers, a rate limit and a signing secret.Webhook Engine › Destinations
EventSomething that happened, such as user.created or hcms.entry.published. Each destination subscribes to one or more.Subscribed Events on the destination form
DeliveryOne attempt to send one event to one destination. Each attempt is a row in the log.Webhook Engine › Delivery Logs
Test ConsoleSends one payload of your choice to a destination straight away, and shows the full request and response.The destination's Test Console link

Which events you can choose

The event list is built from the add-ons you have turned on:

FromEvents
Webhook Engine itselfuser.created, user.updated, user.deleted
Blog, when it's onpost.created, post.updated, post.deleted, category.created, category.updated, category.deleted
Headless CMS, when it's onSeven events, such as hcms.entry.published and hcms.delivery.changed. See How the Headless CMS works.

If you turn an add-on off, its events leave the list, but destinations already subscribed to them keep the subscription. The form marks such an event no longer offered, so you can see it and remove it on purpose. The full list, with what each event sends, is in Webhook payloads, headers and events.

What happens when an event occurs

  1. Your Laramin finds every destination whose Status is Active and that subscribes to the event.
  2. It checks the destination's Event Filters. If a rule doesn't match, nothing is sent to that destination.
  3. It queues one delivery per destination, spaced out to respect the destination's Rate Limit (per minute).
  4. A background worker sends the delivery: a POST to the Endpoint URL, with the JSON payload, the signature headers and your Custom Headers. It waits up to 10 seconds for an answer.
  5. Any 2xx answer counts as success. Anything else, or no answer within 10 seconds, counts as a failure.
  6. A failed delivery is tried again after 5 seconds, 15 seconds, 1 minute and 5 minutes: up to 5 attempts in all. Each attempt is logged.
Flowchart of one event's path: Active subscribed destinations, Event Filters, queued POST to the Endpoint URL, then Success on 2xx or up to 5 retried attempts, Suspended after 20 failures, all logged.

Deliveries are background jobs, so your Laramin's queue worker must be running. If it isn't, deliveries wait and nothing is sent. See An add-on is stuck or failed for how to check the queue.

Signing

Each destination gets its own signing secret when it's created. Every delivery carries an X-Laramin-Signature header: a code made from the payload and that secret. The receiving system makes the same code with its copy of the secret. If the two match, the message is genuine and wasn't changed on the way.

With Sign the timestamp on, the signature also covers the time the delivery was sent. The receiver can then refuse old messages, so someone who captured a delivery can't send it again later. New destinations have it on.

No screen shows a destination's signing secret, so whoever builds the receiver can't copy it from the app. See Verify webhook signatures and handle retries.

When a destination keeps failing

Each failed attempt adds one to the destination's Consecutive Failures. A successful delivery sets it back to 0. At 20 failures in a row, your Laramin sets the destination's Status to Suspended and stops sending to it, so a broken receiver doesn't pile up failed requests. Nothing is sent to a suspended destination until you set it back to Active. See Deliveries fail or a destination is suspended.

What a payload contains

For user.*, post.* and category.* events, the payload carries the record's stored fields as they were after the change. Passwords and two-factor secrets are always left out, but names, email addresses and other personal details are included. Send them only to systems you trust, over https://.

Headless CMS events carry ids, keys and versions, never content.

How it relates to

Next steps