Outgoing webhooks

Pour :Administrateur

View of the 'webhooks' page

An outgoing webhook is an HTTP notification that Unisoft sends to a URL of your choice as soon as a business event occurs in your organization (a successful payment, a submitted form, a new contact created…). It is the ideal mechanism to react in real time without having to poll the API in a loop.

Open the Webhooks tab

1. 1

   Go to the Developers page

   Type the URL /app/developpeurs/tabs in the address bar.

2. 2

   Click the 'Outgoing webhooks' tab

   The tab is to the right of the API Keys tab.

Understanding the table

The central table lists the webhooks configured for your organization. For each, you see:

Column	Content
Name	The label you chose (e.g., Make - Mailchimp sync)
URL	The target URL, partially masked so as not to expose the secret path
Events	The listened events (tags)
Last success	Relative date of the last successful send, or never
Status	Active (green), Inactive (gray), Quarantined (orange), or number of failures (yellow)
Actions	Test, Edit, Regenerate secret, Delete buttons

Create a new webhook

1. 1

   Click 'New webhook'

   The button is at the top right of the tab. A modal opens.

2. 2

   Give a descriptive name

   Enter a descriptive name like Make - Mailchimp sync or Slack donation alerts. You will find it later when you have several webhooks.

3. 3

   Fill in the target URL

   The URL provided by your tool (Make catch hook, Zapier webhook, your script endpoint…). HTTPS mandatory — URLs in http:// or pointing to local addresses are not accepted.

4. 4

   Choose the events to receive

   Select one or several events from the list (see the table below). You can select several if the same URL must receive different types of notifications.

5. 5

   Click 'Create the webhook'

   A new modal appears immediately with the signing secret.

6. 6

   Copy the secret right away

   Click "Copy the secret". You will never see this secret again once the modal is closed — paste it immediately into your tool or your password manager.

7. 7

   Confirm

   Click "I have copied the secret" to close the modal.

⛔

Shown only once

The secret is only shown once, just after creation. If you lose it, you will need to use the Regenerate secret button (the old one will be invalidated).

Available events

Each webhook listens to one or several events. Here are the main ones available:

Event	Triggered when…
paiement.success	A payment is successfully collected
paiement.refunded	A payment is refunded
form.submitted	A form is submitted by a visitor
contact.created	A new contact is created in the Contacts module
*	All events (to reserve for debugging or centralized tools like log aggregators)

ℹ

Evolving list

Other events may be added in future releases. The modal selector always displays the up-to-date list available for your organization.

The HMAC signature: verify the notification really comes from Unisoft

When Unisoft sends a notification to your URL, it attaches a cryptographic signature computed with the shared secret. Your tool must verify this signature to ensure the notification is legitimate (and not a malicious call imitating Unisoft).

Principle

1. Unisoft computes an HMAC SHA-256 of the request body, using your secret as the key.
2. The signature is attached to the HTTP request (usually in a X-Unisoft-Signature header or equivalent).
3. Your tool recomputes the signature on its side from the received body and its secret.
4. If the two signatures match, the notification is authentic.

On the Make / Zapier side

Make and Zapier often offer a native signature validation in their Webhook module. Simply fill the secret in the dedicated field: the platform verifies automatically.

On the in-house script side

If you write your own endpoint, your code must:

1. Read the raw body of the HTTP request.
2. Read the signature in the header.
3. Compute the HMAC SHA-256 of the body with your secret.
4. Compare the two. Reject (with a 401 code) if the signature does not match.

The exact format of the header and any timestamp for replay protection are described in the interactive Swagger documentation (API Documentation button).

Example payload received

When a new payment is collected, your URL receives an HTTP POST request with a JSON body whose structure looks like:

{
  "type": "paiement.success",
  "createdAt": "2026-05-18T10:32:14.000Z",
  "organisation": "org_abc123",
  "data": {
    "id": "pmt_xyz789",
    "amount": 5000,
    "currency": "EUR",
    "contact": {
      "id": "ctc_def456",
      "firstName": "Sarah",
      "lastName": "Cohen",
      "email": "sarah.cohen@exemple-unisoft.org"
    },
    "reason": "Donation to the Main cash register"
  }
}

The exact format (available fields, naming conventions) is documented event by event in the Swagger.

Test a webhook

The Test button sends a dummy webhook.test event to your URL to check connectivity, without waiting for a real event to occur.

1. 1

   Click the Test button

   Play icon (▶) in the Actions column of the webhook row.

2. 2

   Check in your tool

   Make / n8n / Zapier should receive a POST request with type: "webhook.test". If yes, your integration is correctly configured.

3. 3

   In case of failure

   Check: is the URL really in HTTPS? Does the target server accept external requests? Does the firewall authorize Unisoft's IP?

★

To use right after creation

Always run a Test right after creating a webhook. This avoids discovering weeks later that no event was arriving at destination.

Edit a webhook

1. 1

   Click the Edit icon

   Pencil icon in the Actions column.

2. 2

   Adjust the fields

   You can edit the name, the URL or the list of events. The secret remains unchanged.

3. 3

   Save

   Changes are taken into account from the next event onwards.

Regenerate the secret (rotation)

If you suspect your secret has been compromised (appeared in a public Git repo, former collaborator, etc.), regenerate it immediately.

1. 1

   Click the Regenerate icon

   Refresh icon (orange) in the Actions column.

2. 2

   Confirm

   A confirmation request reminds you that the old secret will be invalidated immediately.

3. 3

   Copy the new secret

   A modal displays the new secret, only once. Copy it and replace the old one in your destination tool.

⚠

Coordination required

During the brief interval between regeneration and updating your tool, the received webhooks will not be able to be validated by it. Prepare the replacement ahead of time in your tool to minimize the disruption.

The circuit-breaker: automatic protection in case of errors

If your target URL fails several times in a row (server down, wrong URL, expired HTTPS certificate…), Unisoft automatically disables the webhook for some time. The status then changes to "Quarantined" (orange tag).

This protection prevents flooding your server with calls that fail and wasting resources on both sides.

How to exit quarantine

1. 1

   Identify the cause of the failure

   Check your tool's or your server's logs. Verify that the URL responds correctly with a 2xx HTTP code.

2. 2

   Test the webhook

   Use the Test button to verify the URL works again.

3. 3

   Edit the webhook

   Open the edit form and save (even without modification) to reset the error counter.

Delete a webhook

1. 1

   Click the Delete icon

   Red trash icon in the Actions column.

2. 2

   Confirm

   The webhook is permanently deleted. No more notifications will be sent to this URL.

Practical case: synchronize new contacts to Mailchimp in real time

1. 1

   Prepare a Make scenario

   Create a new Make scenario starting with the Webhook → Custom webhook trigger. Make generates a unique URL like https://hook.make.com/abc123xyz.... Copy it.

2. 2

   Create the webhook in Unisoft

   Webhooks tab → New webhook. Name: Make - Mailchimp sync. URL: the one generated by Make. Events: contact.created. Create and copy the displayed secret.

3. 3

   Test from Unisoft

   Click the Test button in Unisoft. Make should receive the event and display the received payload. If yes, validate the trigger.

4. 4

   Add the Mailchimp module in Make

   Connect your Mailchimp account, then add the Add/Update Subscriber action by mapping the fields received from the webhook (firstName, lastName, email) to the Mailchimp fields.

5. 5

   Activate the scenario

   Activate the scenario in Make. From now on, every new contact in Unisoft will be added to Mailchimp in a few seconds.

Pitfalls to avoid

Pitfall	Consequence	Solution
URL in HTTP instead of HTTPS	Webhook refused at creation	Enable HTTPS on your endpoint (Make, Zapier and n8n do it natively)
Not verifying the HMAC signature	Anyone can imitate Unisoft and call your URL	Enable signature validation in your tool or implement it in your script
Storing the secret in clear in a configuration file	Possible compromise	Use environment variables of your tool or a vault
Ignoring the quarantine	Your events are lost during the disruption	Monitor the status and react when a webhook turns orange
Sending a slow HTTP response (>30 s)	Unisoft considers the call as a failure and increments the error counter	Respond quickly (200 OK) and process asynchronously in your tool

Takeaways

• An outgoing webhook is an HTTP notification sent by Unisoft to your URL as soon as a business event occurs.
• The URL must be in HTTPS and the signing secret is shown only once.
• The HMAC SHA-256 signature guarantees that the notification really comes from Unisoft — verify it on the destination tool side.
• The Test button sends a dummy event useful to validate the configuration.
• The circuit-breaker temporarily disables a webhook that fails too often — fix the cause, test again, then save to reset.

Go further

• Developers overview — the two integration building blocks
• API Keys — read data on demand