Webhooks

A webhook is essentially a user-defined HTTP callback that automatically notifies you or performs an action when a specific event occurs.

For this guide, it is assumed that you are familiar with basic web development concepts, RESTful APIs, and have administrative access to both the Wingspan and the service where you want the webhook to send data.

Benefits and uses

Creating a webhook to listen to payment and invoice events in Wingspan can offer a range of benefits.

Real-Time Updates

• Instant Notifications: Receive real-time alerts as soon as a payment or invoice event occurs.
• Reduced Latency: Webhooks are event-driven and can provide near-instantaneous updates.

Automation

• Streamlined Processes: Eliminate the need for manual checks by integrating the webhook directly into existing workflows.
• Batch Processing: Automatically queue up payroll tasks based on real-time triggers.

Data Consistency

• Data Sync: Keep all data sources in sync by updating them in real-time.
• Error Checks: Identify errors or inconsistencies in the data immediately as they occur.

User Experience

• Timely Notifications to Users: Automatically send alerts or updates to end-users when their payment or invoice status changes.
• Improved Transparency: Offer detailed transaction logs and event history.

Efficiency

• Reduced Load: Eliminates the need to poll the server repeatedly to check for new events, thus reducing server load.
• Resource Optimization: Allows system resources to be used more effectively, as they're only activated when needed.

Customization and Flexibility

• Event Filtering: Choose to listen only to specific types of events that are most relevant to your application.
• Multiple Endpoints: Direct different types of events to different URLs for specialized handling.

Business Logic

• Business Rules: Implement complex business rules that execute automatically based on real-time events.
• Audit Trail: Maintaining an accurate and immediate log of all payment and invoice-related activities.

Security

• Fraud Detection: Detect potentially fraudulent activities in real-time.
• Compliance: Ensure that operations are performed according to relevant legal and business standards by implementing real-time checks.

Analytics and Reporting

• Dynamic Metrics: Produce real-time analytics and KPIs.
• Historical Data: Maintain an ongoing record of events for future analysis.

Cost Savings

• Reduced Operational Costs: Automation and streamlining can lead to a reduction in manpower and operational costs.
• Scalability: Webhooks are generally easier to scale compared to traditional, more monolithic architectures.

Prerequisites

• Administrative access to Wingspan
• A server to host your webhook with a public-facing URL
• Programming, such as Python, Node.js, or similar
• Access to a code editor

To Configure a Webhook in Wingspan

The process of configuring a webhook for Wingspan consists of:

• Choosing the events triggers
• Configuring a webhook endpoint on your server
• Generating a shared secret
• Calling the Wingspan webhook API: /integrations/webhooks/preference

Choose your Event Triggers

The first step in configuring your webhook is to choose which events you want to listen for. Depending on your business needs, you can configure your webhook to listen to a variety of events. For example, assume that you want to send a notification to your accounting platform each time a payment fails. This can be achieved by including the payoutFailedAt event in the request body of the /integrations/webhooks/preference endpoint.

The table below lists the various Wingspan Invoice and Payable events.

Alternatively you can call the integrations/webhooks/eventnames endpoint to retrieve a list of all current Invoice and Payable events. Wingspan recommends that calling the eventnames endpoint as it ensures that you have the most up-to-date events that are available to Wingspan users.

To call the eventnames endpoint:

1. Log in to Wingspan as an administrator.

2. From the Home page, navigate to Data & Integrations > Developer.

3. On the Developer page, use either the Copy or Generate new token button to retrieve your API authorization token. This token is used to authorize your calls to the Wingspan API.

4. Get a list of event IDs used in Wingspan with the /integrations/webhooks/eventnames endpoint.

   1. Open your favorite API client and call:

      JSON

      curl --request GET \
      
      --url https://api.wingspan.appintegrations/webhooks/eventnames \
      --header 'accept: application/json'
      --header 'authorization: Bearer <Your Authorization Token>'
      

5. If the call is successful, it returns a list of Wingspan event names. Choose the events that you want to configure your webhook endpoint to listen for.

Create a Webhook Endpoint on Your Server

There are many strategies to consider when creating an endpoint that listens for a webhook. This procedure covers the basic requirements and gives a rudimentary example of how this can be achieved. For best results, consult your IT department for the best possible strategy for your infrastructure.

To create a webhook endpoint on your server

1. On your server, create a new endpoint that listens for the webhook. For example, if you're using Python with Flask:

   Python

   from flask import Flask, request, jsonify
   
   app = Flask(__name__)
   
   @app.route('/webhook', methods=['POST'])
   def webhook_listener():
   	data = request.json
   	# Perform actions based on the data received
   	# ...
   	return jsonify({'status': 'success'}), 200
   

2. Using your preferred method, generate your sharedSecret for the webhook.

   Generating a shared secret for a webhook is an essential step to ensure the security and integrity of the data being sent and received. The shared secret is used to create a cryptographic signature that can be used to verify the authenticity of the incoming webhook payloads.

   In this case, the sharedSecret is an encrypted string which drives webhook authentication on the client-side via Hash-based Message Authentication Code (HMAC), specifically HMAC-SHA256.

   You can generate a shared secret in a number of ways.

   1. Using Built-in Tools: Many programming languages have built-in libraries to generate cryptographically secure random strings that can serve as a shared secret.
   2. Using Command-Line Tools: On a UNIX-based system like Linux or macOS, you can generate a secure random string using the openssl tool.
   3. Using Web-Based Tools: There are various web-based tools available that can generate cryptographically secure random strings. Be cautious when using this method to ensure the tool you use is from a reputable source.

3. Deploy this server code so that it’s accessible publicly. Note down the public-facing URL of your webhook endpoint, for example, https://yourdomain.com/webhook.

Configure the Webhook in Wingspan

Now that you have your events, a published endpoint URL, and shared secret you can call the Wingspan webhooks/preference endpoint to finish the webhook configuration.

1. Return to your favorite API client and call the /integrations/webhooks/preference endpoint.
   1. In the call, you use the POST method to send the list of events that you want your webhook to listen for. For example, InvoicePaid and InvoiceSent.
   2. You include your URL for your public-facing URL of your webhook endpoint, the shared secret and the events that you want your webhook to listen for. For example:

curl --request POST \
     --url https://api.wingspan.app/integrations/webhooks/preference \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <Your Authorization Token>'
 \
     --data '
{
  "url": "https://yourdomain.com/webhook",
  "sharedSecret": "string",
  "subscribedEvents": [
    "InvoicePaid",
    "InvoiceSent"
  ]
}
'

After the call returns a 200 code, event data begins flowing to your webhook and your application.