How to use webhooks in magnews

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

This page provides the technical documentation required to implement them. If you would like to understand when and why to use webhooks from a functional perspective, please refer to the dedicated use case article.

Supported events (topics)

Webhooks work through events, called topics.
Each topic represents an action or a change that occurs within magnews and can generate a notification to an external system.

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

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

Contact management

These events are generated when the status or profile of a contact changes in the database:

• contacts/create – a new contact is created in magnews.
• contacts/update – an existing contact’s data is updated.
• contacts/unsubscription – a contact requests to unsubscribe from communications.
• contacts/delete – a contact is deleted from the system.

These topics are useful, for example, to keep databases aligned between magnews and external systems.

Communications

Events related to standard sending campaigns:

• communications/msg/sent – message sent
• communications/msg/open – message opened
• communications/msg/click – link clicked
• communications/msg/conversion – conversion tracked
• communications/msg/bounce – delivery error
• communications/msg/complaint – marked as spam

These topics allow you to monitor communication performance even outside of magnews.

Transactional messages

Events similar to communication events, but related to transactional messages:

• transactionals/msg/sent – message sent
• transactionals/msg/open – message opened
• transactionals/msg/click – link clicked
• transactionals/msg/conversion – conversion tracked
• transactionals/msg/bounce – delivery error
• transactionals/msg/complaint – marked as spam

These are designed to integrate magnews with systems that manage operational notifications, such as order confirmations or password resets.

Workflows

Events generated by messages similar to transactional ones, but within automation journeys:

• workflows/msg/sent – message sent
• workflows/msg/open – message opened
• workflows/msg/click – link clicked
• workflows/msg/conversion – conversion tracked
• workflows/msg/bounce – delivery error
• workflows/msg/complaint – marked as spam

These topics make it possible to track and react to contact behavior as they move through a specific workflow path.

Technical guide to subscriptions

Webhook subscription management is handled through a dedicated REST resource. A subscription defines where magnews should send notifications (endpoint) and which events it should forward (topics).

Creating a subscription

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

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

To see a complete example of the API request for a subscription, refer to our REST API documentation.

URL verification

When a subscription is created, magnews performs a verification of the provided URL to ensure that the endpoint is reachable and responds correctly.

1. magnews sends a POST request to the provided URL with a JSON body {"verify": true}.
2. The request includes the X-magnews-hmacsha256 header (see the “Signature verification” section).
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. The id is required; uri, topics, and status are optional.
• DELETE /webhooks/delete/{id}
  Deletes a subscription. Returns 200 if the operation succeeds 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 code is considered an error and the event will be retried (for more details, see the “Error handling, retry and backoff” section).

HTTP headers

Each notification includes the following technical headers:

• X-magnews-webhook-topic
• X-magnews-webhook-subscriptionid
• X-magnews-webhook-event-timestamp
• X-magnews-hmacsha256

Signature verification (HMAC-SHA256)

To ensure that the request actually comes from magnews, verify the HMAC-SHA256 signature included in the X-magnews-hmacsha256 header.

1. Retrieve the raw body of the request.
2. Compute the HMAC-SHA256 using your client_secret.
3. Compare the result with the header value.

HTTPS requirements

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

Event delivery timing

Webhooks operate in near real-time.

Under normal conditions, notifications are delivered within seconds, but short delays may occur in case of processing queues or high load.

Integrations should therefore treat webhooks as eventually consistent, not synchronous notifications.

Error handling, retry, and backoff

Each subscription maintains its own event progress. In case of errors, magnews applies progressive backoff to avoid excessive retry attempts.

If consecutive errors exceed predefined thresholds, the subscription may be automatically suspended. After resolving the issue on the destination endpoint, the subscription must be manually reactivated.

Monitoring

A monitoring view is available at: Monitor > Development > Webhooks.

The screen displays:

• Endpoint (URI)
• Subscribed topics
• Last execution
• Backoff status
• Subscription status (active or suspended)

If consecutive delivery errors are detected, automatic system notifications are triggered:

• Malfunction warning when an error threshold is exceeded.
• Suspension notification if the subscription is automatically suspended.

Notifications are sent to the main account contacts (e.g. Commercial Contact and Customer Contact). No manual configuration of recipients is required or available.

Once the technical issue has been resolved, the suspended subscription must be manually reactivated.