Falaah Falaah AI

Setting Up Webhooks

Send Muin events to your systems or receive theirs: create an incoming or outgoing webhook, pick events, verify signatures and fix failed deliveries.

Webhooks let another system hear about Muin events the moment they happen (outgoing), or let another system send events into Muin (incoming).

Webhooks live at Settings → Integrations → Webhooks and are available to owners and admins.

When you’d use this

  • Your website or CRM should update when an invoice is paid or someone registers for an event.
  • You want a notification in another tool when a document finishes processing.
  • An outside system needs to push events into Muin to start a workflow.
  • A receiving server was down and you need to resend the deliveries it missed.

Create an outgoing webhook

  1. Open Settings → Integrations → Webhooks and select the outgoing tab.
  2. Click Create Webhook.
  3. Enter a Name, the URL that should receive events (HTTPS), and an optional Description.
  4. Tick each event you want sent, or leave the list empty to receive every event. The picker lists only events Muin can actually deliver today:
    • Documents: document.processed
    • Invoices: invoice.created, invoice.approved, invoice.paid
    • Calendar and events: calendar.event.published, calendar.event.unpublished, calendar.event.cancelled, event.capacity_full
    • Registrations: registration.created, registration.cancelled, registration.checked_in, registration.no_show
  5. Click create. Muin shows the Webhook Secret once. Copy it now; you need it to verify signatures.
  6. Open the webhook and click Send Test to confirm your server receives a delivery.

Create an incoming webhook

  1. On the same page, select the incoming tab and click Create Webhook.
  2. Enter a Name and Description, then create it.
  3. Copy the Webhook Secret shown once. Then open the webhook and copy its Endpoint URL (under Where to send deliveries).
  4. In the sending system, sign each request: put an HMAC-SHA256 signature in the X-Muin-Signature header as sha256=<hex>, put the Unix time in X-Muin-Timestamp, and sign <timestamp>.<body>. Requests older than 5 minutes are refused, so a captured request cannot be replayed later.

What it affects

  • Each outgoing delivery is a POST with the event in the body and the headers X-Muin-Event, X-Muin-Delivery-Id, X-Muin-Signature and X-Muin-Timestamp.
  • The webhook page shows Status, Total Deliveries, Failures, Consecutive Fails, Subscribed Events and Recent Deliveries.
  • Disable stops deliveries without deleting the webhook; Enable turns them back on.
  • Regenerate Secret replaces the signing secret immediately. Update your server’s verification at the same time.

When it goes wrong

What you see Why What to do
A delivery shows failed after several attempts Your server returned an error or did not answer within 30 seconds. Muin tries 5 times in total, waiting 1, 2, 4 and then 8 minutes between attempts. Fix the server, then click retry on the delivery under Recent Deliveries.
Status reads Circuit Open 5 deliveries in a row failed, so Muin paused this webhook for 30 minutes to stop hammering your server. Fix the server. Deliveries resume on their own after the pause.
Your server rejects the signature It is verifying with an old secret, or it re-serialized the body before hashing. Verify against the raw request body and the current secret. See Webhooks API for code.
An event you subscribed to never arrives It is not one of the events Muin can deliver today. Older subscriptions to such events stay visible so you can remove them. Edit Subscribed Events and pick from the list above.

Next step