Integrations

Error Notifications

# Overview

PackageX can automatically send email notifications when integration errors exceed a configured threshold. This feature helps your team proactively monitor the health of both outgoing integrations and incoming webhooks without constantly checking logs manually.

Error notifications are available for:

• Outgoing integrations (data pushed from PackageX to external systems)
• Incoming webhooks (data received from external systems into PackageX)

# How It Works

1. Each time an integration request results in an error, PackageX increments the error count for that integration type.
2. When the error count within the configured time window exceeds your organization's failure_limit, an internal event is published.
3. All users who have the corresponding event in their profile's notification_events array receive an email notification.
4. After a notification is sent, a cooldown period equal to the configured failure_interval prevents duplicate notifications.

# Configuration

Error notification settings are configured on the organization's settings.integration_notifications object. You can update these via the organization update endpoint.

# Outgoing Integration Settings

# Incoming Webhook Settings

# Failure Interval Values

The failure_interval field accepts the following values:

# Example: Enable Outgoing Integration Error Notifications

To receive a notification when 5 or more outgoing integration errors occur within a 1-hour window:

        {
  "settings": {
    "integration_notifications": {
      "outgoing": {
        "failure_limit": 5,
        "failure_interval": "mins_0060"
      }
    }
  }
}

      

# Example: Enable Incoming Webhook Error Notifications

To receive a notification when 10 or more incoming webhook errors occur within a 24-hour window:

        {
  "settings": {
    "integration_notifications": {
      "incoming": {
        "failure_limit": 10,
        "failure_interval": "mins_1440"
      }
    }
  }
}

      

# Disabling Notifications

Set failure_limit to 0 to disable notifications for either type:

        {
  "settings": {
    "integration_notifications": {
      "outgoing": {
        "failure_limit": 0
      },
      "incoming": {
        "failure_limit": 0
      }
    }
  }
}

      

# User Subscription

For a user to receive integration error notification emails, the corresponding event name must be present in the user's notification_events array on their profile. The relevant event names are:

Users who do not have these events in their notification_events array will not receive the email, even if the organization's threshold is met.

# Email Notification Details

When a notification is triggered, the following email is sent:

• From: no-reply@packagex.io
• To: All users subscribed to the event
• Subject: Integration error threshold exceeded
• Contents:
  • The number of errors that triggered the notification
  • The organization name
  • A download link for a CSV file containing the recent error details
• CSV Link: A signed Google Cloud Storage URL valid for 24 hours

# Important Notes

• Error notification events (outgoing_integration__error and incoming_webhook__error) are internal-only events. They are not dispatched to your webhook endpoints.
• The cooldown mechanism uses the last_failure_at timestamp. After a notification is sent, no further notifications are sent until the failure_interval has elapsed.
• Error counts are calculated from the time of the last notification (or the last 30 days if no previous notification exists).
• Both failure_limit and failure_interval must be configured for notifications to work. A failure_limit of 0 disables the feature entirely.