Skip to content

Set up webhooks in ioumi and receive events

A webhook is an automatic message from ioumi to another program. As soon as something happens in ioumi, for example a contract is signed or a payment comes in, ioumi immediately sends the details to an address of your choice. Your CRM, Make, Zapier, n8n or your own system can react to it, without constantly having to check with ioumi.

The difference from the API: with the API, your system asks ioumi. With a webhook, ioumi gets in touch on its own. Learn more about the API in API.

  • Contract signed: create the onboarding in your project tool, send a welcome email, mark the opportunity in your CRM as won
  • Payment failed: create a task in your CRM or notify your team in chat
  • Invoice created: pass the invoice on to your bookkeeping automatically. This event is also what invoicing from your own invoicing software is built on, see External billing mode.
  • Contact created or changed: sync customer data with your CRM
  1. Open Settings › Integrations.
  2. Under Webhooks, click Add Webhook.
  3. Enter the URL that ioumi should send the messages to. In Make, Zapier or n8n, you get this address when you create a webhook as a trigger there.
  4. Enter a Description that later tells you what the webhook is for.
  5. Choose the Events ioumi should notify you about.
  6. Click Add.

In the list, you can edit, temporarily deactivate or delete a webhook at any time.

AreaEvents
Dealscreated, sent, viewed, signed, declined, canceled, expired
Paymentssucceeded, failed
Invoicescreated
Credit notescreated
Contactscreated, updated, deleted

Every message contains the data of the deal, payment, invoice or contact concerned. You can find exactly which fields are included in the API documentation under Settings › Integrations › API Documentation.

As soon as your customer signs the contract, ioumi sends the “signed” event (deal.signed). This is the right event for workflows after the deal is closed, such as onboarding, course access or the status in your CRM.

What happens if your system is unreachable?

Section titled “What happens if your system is unreachable?”

ioumi expects a successful response within 30 seconds. If none comes, ioumi automatically tries again: the first delivery plus up to four retries after 5 minutes, 30 minutes, 2 hours and 6 hours. If the last retry also fails, ioumi stops delivering this message. So make sure the address is permanently reachable.

Every message is a POST with JSON and these headers:

HeaderContent
X-Webhook-Eventthe event, for example deal.signed
X-Webhook-IDunique ID of the message, the same for retries
X-Webhook-Attemptwhich delivery attempt this is
X-Webhook-Signaturetimestamp and signature in the format t=…,v1=…

To keep your connection secure and reliable, keep three points in mind when receiving messages:

  • Verify the signature: The signature is an HMAC-SHA256 of the timestamp and the JSON content, created with the webhook secret. Verify it before you process the message. This ensures it really comes from ioumi. The API documentation describes how to get the secret and verify the signature.
  • Detect duplicate messages: If a response gets lost on the way, the same message can arrive a second time. So process each X-Webhook-ID only once.
  • Respond quickly: Respond immediately with a 2xx status and do any heavy work afterwards in the background.