In this section · 4 articles

Add a webhook destination

Set up an address that receives a signed message whenever chosen events happen in your Laramin: pick the events, add filters and headers, choose how deliveries are signed, and set a rate limit.

Applies to
Webhook Engine 2.2 and later
Who can do this
Platform owner, Administrator
Permission
feature.webhook.destination.create
Where
Webhook Engine › Destinations
On this page

A destination is an address on another system, such as your CRM, a chat tool or your own app, that should hear about events in your Laramin. Add one destination per receiving system.

Before you start

  • You need Create Destination (feature.webhook.destination.create). To open the list you need List Destination (feature.webhook.destination.list), and to change a destination later, Edit Destination (feature.webhook.destination.edit).
  • Get the receiving address from whoever runs the receiving system, for example https://hooks.example.com/laramin. Ask them whether their receiver checks the timestamp-bound signature (version 2). New receivers should.
  • Your Laramin's queue worker must be running, or deliveries wait and are never sent.

Steps

  1. In the sidebar, open Webhook Engine › Destinations.

    The Webhook Destinations list under Webhook Engine › Destinations, showing seven destinations with their endpoint URLs and subscribed events, and the New Webhook Destinations button highlighted.
  2. Select New Webhook Destinations.

    The Create Webhook Destinations form with Name Order system, Endpoint URL https://hooks.example.com/laramin, user.created subscribed, Status Active, Rate Limit 60 and Sign the timestamp on.
  3. In Name, enter a name you'll recognize in the delivery log, such as Order system.

  4. In Endpoint URL, enter the receiving address. Use an https:// address: the payload can include names and email addresses.

  5. In Subscribed Events, choose the events this system should receive, for example user.created. You must choose at least one.

  6. Leave Status on Active. Choose Inactive to set the destination up now and start sending later.

  7. In Rate Limit (per minute), leave 60 unless the receiver asks for fewer requests. Deliveries to this destination are spaced out to stay within it.

  8. Optional: under Custom Headers, add any header the receiver needs, such as an API key it expects. Enter the name in Header and the value in Value.

  9. Optional: under Event Filters, add rules to send only some events. See Send only some events below.

  10. Leave Sign the timestamp on, unless the receiver only understands the older, payload-only signature.

  11. Select Save.

You see Webhook destination Order system created successfully!, and the destination is listed with Status Active and Consecutive Failures 0. Your Laramin creates the destination's signing secret for you.

Careful: No screen shows the signing secret, not even once after saving. The receiver needs it to check signatures. See Verify webhook signatures and handle retries for what the receiver's developer can do.

Send only some events

Event Filters let a destination receive an event only when the record matches every rule. With no rules, it receives every event it subscribes to.

Each rule has a Field, an Operator (Equals or Not equals) and a Value:

  • For user.*, post.* and category.* events, Field is the name of a field on the record, as it appears in the payload's data, for example email. The record is checked as it is after the change.
  • For Headless CMS events, Field is a key in the payload. Use a dot to reach a nested key, for example entry.slug or space.
  • Values are compared as text, loosely: 1 matches a field stored as 1 or true. Letter case counts, so Published doesn't match published.
  • A rule with an empty Field is ignored.

For example, a destination subscribed to hcms.entry.published with the rule Field space, Equals, Value website hears only about entries published in the content space whose key is website.

The Event Filters section of the destination form with one rule: Field space, Operator Equals and Value website, so only entries published in the website content space are sent.

Custom headers

  • Each header is sent with every delivery and every test.
  • If a custom header has the same name as one Webhook Engine sets, such as X-Laramin-Signature, Content-Type or User-Agent, Webhook Engine's value is sent instead.
  • Header values are stored encrypted. They are, however, copied into each delivery's log entry, where anyone with View Log can read them. Prefer a dedicated key for the receiver over a password you use elsewhere.

Sign the timestamp

SettingWhat the receiver must checkHeader sent
On (Timestamp signed)The timestamp and the payload together. The receiver can refuse messages that are too old.X-Laramin-Signature-Version: 2
Off (Payload only)The payload only. A captured message would still pass the check if sent again.No version header

Destinations created before Webhook Engine 2.2.0 were set to Payload only when it was installed, so their receivers kept working. To protect one, have the receiver updated to accept version 2 first, then turn Sign the timestamp on. Turning it on before the receiver is ready makes every delivery fail its signature check.

Rate limit

Deliveries to one destination are spaced at least 60 ÷ Rate Limit seconds apart, rounded up to whole seconds. So any value above 60 behaves like 60: a destination receives at most about one new delivery per second. Retries of a failed delivery follow their own timing, not the rate limit.

Change, pause or remove a destination

  • Change: open the row's actions menu and select Edit. Change the fields, then select Save. You see Webhook destination name updated successfully!
  • Pause: edit it and set Status to Inactive. Deliveries already waiting are skipped, and nothing new is sent.
  • Resume a suspended destination: edit it and set Status to Active. Consecutive Failures goes back to 0.
  • Delete: select Delete in the row's actions menu. The destination goes to the trash and receives nothing. Its delivery log stays.
  • Restore: in the list's Trashed view, select Restore.
  • Delete forever: in the Trashed view, select Delete forever and type the destination's name to confirm. This also deletes every delivery log entry for that destination, and can't be undone.

For the Trashed view and acting on several destinations at once, see Delete, restore and act on records in bulk.

What happens next

Test the destination to check that the receiver answers. Then make a change that fires one of its events and look for it in Webhook Engine › Delivery Logs.