Come si usano i webhook in magnews

Webhooks are a mechanism that allows magnews to automatically send notifications to external systems when a specific event occurs (for example a contact is created or an email is opened).

This page contains the technical documentation to implement them. If instead you want to understand when and why to use webhooks from a functional perspective, see the use-case article and integration scenarios.

Supported events (topics)

Webhooks operate via events, called topics.
Each topic represents an action or a change that happens inside magnews and can trigger a notification to an external system.

When you create a webhook subscription you choose which topics to listen to, depending on the information you need.

Below you will find the available topics grouped by functional area.

Technical guide to subscriptions

Webhook subscriptions are managed via a dedicated REST resource. A subscription defines where magnews should send notifications (the endpoint) and which events it should forward (topics).

Creating a subscription

To activate a webhook, send a POST request to /webhooks/create specifying:

• uri
  The URL of your endpoint that will receive notifications (e.g. https://your-system.com/webhook-receiver).
• topics
  A comma-separated string with the desired topics (e.g. contacts/create,contacts/update).

For a complete example of the subscription API request, see our REST API documentation.

URL verification

When creating a subscription, magnews verifies the provided URL to ensure the endpoint is reachable and responds correctly.

1. magnews sends a POST to the provided URL with JSON body {"verify": true}.
2. The request includes the X-magnews-hmacsha256 header (see "Signature verification").
3. Your system must validate the signature and respond with 200 OK.

If verification fails, the subscription is not created and the endpoint returns an error. Creation may also fail if the maximum number of subscriptions per account has been reached.

Updating and deleting a subscription

Once created, you can manage a subscription using:

• POST /webhooks/update
  Updates an existing subscription. id is required; uri, topics and status are optional.
• DELETE /webhooks/delete/{id}
  Deletes a subscription. Returns 200 if successful and 404 if the subscription does not exist.

Event handling and security

All webhook notifications sent by magnews are POST requests with a JSON body. The receiving endpoint must respond with 200 OK to confirm receipt: any other status is considered an error and the event will be retried (see "Error handling, retry and backoff" for details).

HTTP headers

Each notification includes the following technical headers:

• X-magnews-webhook-topic: the topic that triggered the event (e.g. contacts/update).
• X-magnews-webhook-subscriptionid: the unique subscription ID.
• X-magnews-webhook-event-timestamp: the event timestamp in ISO 8601 format (UTC).
• X-magnews-hmacsha256: security signature of the payload.

Signature verification (HMAC-SHA256)

To ensure the request comes from magnews, verify the HMAC-SHA256 signature in the X-magnews-hmacsha256 header. The signature is calculated from the raw request body and the client_secret associated with the Digital Certificate linked to your application.

1. Retrieve the raw body of the request (without transformations or parsing).
2. Compute the HMAC-SHA256 of the body using the client_secret as key.
3. Compare the resulting hash with the value of X-magnews-hmacsha256.

If the two values match, the request can be considered authentic.

HTTPS requirements

The endpoint must be exposed over HTTPS and present a valid certificate (not self-signed).

Event delivery timing

Event delivery via webhooks happens in near real-time. This means the event is not necessarily delivered at the exact instant it occurs inside the platform.

Under normal conditions notifications are sent within a few seconds, but a delay of several minutes may occur, particularly when processing queues or high load are present.

For this reason integrations should treat webhooks as eventually consistent and not as synchronous notifications.

Error handling, retry and backoff

Each subscription maintains its own event progress. In case of errors, magnews applies retry logic with progressive backoff to avoid frequent attempts to unreachable endpoints.

If consecutive errors exceed predefined thresholds, the subscription may be automatically suspended to avoid inefficient use of resources. In that case, after fixing the problem on the endpoint, the webhook must be manually reactivated (via API call).

Monitoring

A monitoring view is available at Monitor > Development > Webhook, intended for a quick check of subscription status.

The screen shows key information for each webhook, including:

• endpoint (URI)
• subscribed topics
• last execution
• active backoff (if any)
• subscription status (active or suspended)

If the system detects consecutive delivery errors to an endpoint, automatic system notifications are triggered:

• Malfunction warning: sent when a threshold of consecutive errors is exceeded to indicate reachability or response issues.
• Suspension notification: sent when the subscription is automatically suspended due to persistent errors.

Notifications are sent to the email addresses associated with the account's main contacts (for example the commercial contact and the customer contact). Manual configuration of recipient addresses is not available.

If a subscription is suspended, after resolving the technical issue on the external endpoint the subscription must be manually reactivated.