account - webhooks - configuration

  • Updated

Overview

Webhooks allow Neostella to send real-time information to external systems, such as billing or accounting systems, when specific events occur within the platform, enabling the automation of downstream processes. 

 

Prerequisites

  • Endpoint URL, an external destination URL.
  • Target Objects must be configured within the system before their respective events can be selected for subscription.

 

Required Permissions

  • Admin permissions are required for configuration.

 

Configuration Steps

  1. Navigate to Control Center -> Account.
  2. Open the Webhooks tab.
  3. Select the Endpoints tab.
  4. Click on + Add Endpoint button to initiate the configuration.

  1. Enter the destination address into the Endpoint URL field.
  2. Add an optional summary in the Description field.
  3. Select the required events from the Subscribe to events list. 
The Event Catalog tab can be referenced to view all available event types and their specific triggers.
  1. Expand the Advanced Configuration section, if custom routing controls are required.

  1. Check the Enable endpoint throttling? box and a numerical value in the Throttling Rate (per second) field. Delivery rates must be restricted to prevent overload.
  2. Click Create to finalize and deploy the endpoint.

 

Validation

Webhook delivery should be validated to ensure network reachability.

  • The Logs tab must be reviewed to verify message transmission. 
    • Confirm Latest Messages by the EVENT TYPE, MESSAGE ID, and TIMESTAMP of each dispatched payload.

 

Expected Results

The overall health and volume of the Webhook can be monitored from the Activity tab. 

  • It displays a Recent Activity line chart,
  • alongside quantitative metrics for Historical Delivery Attempts,
  • and tracks Successful Attempts and Failed Attempts.

 

Administration and Monitoring

Webhooks can be monitored and managed by clicking on the specific URL from the Endpoints list. The Endpoint interface provides three primary tabs: Overview, Testing, and Advanced.

Overview Tab

  1. The Endpoint URL and Description can be modified post-creation by clicking the Edit button in the respective section.
  2. Delivery Stats (last 24h) provides a visual representation of successful versus failed payload deliveries.
  3. A Signing Secret is provided for the endpoint and can be viewed to authenticate payloads received by the destination server, ensuring security and isolation.  
  4. The Message Attempts section logs granular delivery data. 
    • It displays the EVENT TYPE, TAGS, MESSAGE ID, and TIMESTAMP of each dispatched payload.
    • Message logs can be filtered by All, Succeeded, Failed, and Canceled statuses.
    • Individual payloads can be resent by clicking the Replay button next to a specific message attempt.

 

Testing Tab

This tab is used to ping the configured endpoint with simulated event data to verify connection health.

  1. An event type must be chosen from the Send event dropdown menu.
  2. Based on the chosen event type, a dynamic structural preview is generated under the Schema section.
  3. To trigger the test payload to the Endpoint destination, click the Send Example button..
Test messages transmitted via the Testing tab will not be retried by the system if the delivery fails.

 

Advanced Tab

It is used to manage specialized delivery performance rules and structural configurations.

  1. Endpoint Throttling manages operational constraints, where the existing throttling rate per second is declared or updated.
  2. Custom Headers can be specified by Key and Value pairings.
  3. Custom headers are appended to the transmission payload by clicking the Blue + button.

 

Limitations

  • Circular event chains can be inadvertently created if architecture is not carefully managed. 
  • Message delivery will be throttled or blocked entirely if a low threshold is applied to the endpoint's delivery rate.

 

Common Issues

  • Problem Description: A high volume of identical events is rapidly transmitted, resulting in system performance degradation.  
  • Symptoms: The Activity tab displays a sudden, sustained spike in delivery attempts. The Logs tab shows repetitive events sharing the exact same object and action attributes.
  • Possible Causes: An infinite trigger loop occurs between the Webhook and an internal platform automation. This cycle lacks a natural exit condition and will repeat indefinitely because neither the partner's webhook nor the internal automation has visibility into what triggered the other. Diagnostic Steps: The event metadata should be analyzed. A disproportionate number of events sharing the same ID within a short elapsed window is the most reliable early indicator of a loop.  
  • Resolution Steps: The cycle must be manually interrupted by disabling either the offending Webhook subscription or the internal automation.