Nue Knowledge Center

Nue Docs navigation

Get Started

Configure Products and Prices Create Quotes and Orders Upsell and Renew Subscriptions Understanding Price Calculations Understanding Subscription Term Basis and Proration Ask Nue!

Use Cases

Authenticate API Users Refresh the Salesforce Sandbox

Price Builder

Products Price Book Unit of Measure (UOM)Price and Discount Tags Product Bundle Product Group Product Relationships Percent of Total Multi-attribute Pricing Multiple Currencies Manage Custom Attributes in Price Book Entries Quantity Tier Attributes for Price Tags

Object Model

Nue Object Model Overview Nue Object Model - Price Builder Nue Object Model - Lifecycle Manager Nue Object Model - Billing and Usage Accelerator Understanding Line Types Nue Object Model - Revenue Lifecycle Intelligence

Tutorial

Price Builder Quote Builder Lifecycle Manager Collections Everything Billing Usage Accelerator Lifecycle Intelligence The Nue Platform Integrations Frequently Asked Questions

Lifecycle Manager

Configure Renewal Opportunity Process Configure Create Opportunity Popup Import Subscriptions into Nue Nue Sales Console

Quote Builder

Quote Builder Overview Quote and Order Split Quote Approval Sync Primary Quote to Opportunity Template Quote Manage Filters

Lifecycle Manager

Lifecycle Manager Overview Upsell and Downsell Renew Subscriptions Co-Term Subscriptions Cross-Sell Reconfigure Bundle Subscriptions Adjust Prices Evergreen Subscriptions Cancel Subscriptions Cancel Orders Preview Invoices Manage Service Milestones and Milestone-based Billing

Nue Platform

Manage Custom Fields Product Search Plugin Lookup Filter Plugin Default Value Plugin Invoice Preview Plugin Query Nue Objects using GraphQL Price Tag Search Plugin

Use Cases

Subscription Ramp Pricing Configure Pricing for Different Billing Periods Billing Account Search Setting a Price Floor Revenue Sharing with Partners Custom Payment Terms Update Order Information Customize Auto-numbering Schemes

Everything Billing

Billing Accelerator Overview Billing Parameters Billing Schedules Invoice Status Explained Credit Memos Late Fees - a Debit Memo Use Case Catch-up Bill Run Billing Account Hierarchy Scheduled Sync Jobs Billing Groups Multiple Entities

Collections

Collections Overview Collections Scenarios - Invoicing Collections Scenarios - Credit Memos and Debit Memos Collections Scenarios - Payments Collections Scenarios - Refunds and Reversals Collections Scenarios - Write Off Payment Rules

How-to Guide

Lifecycle Manager Nue Platform

Usage Accelerator

Usage Accelerator Overview The Credit Burndown Usage Model Multiple Credit Pools Credit Proration One-time Credits Integrate with Existing Usage Systems

Developer Resources

Use Cases Object Model API Reference Apex Global Services Self-Service API Guide Client Side Pricing Engine

Lifecycle Intelligence

Revenue Lifecycle Intelligence Subscription and Order Metrics ARR Momentum Booking Dashboard Pipeline Dashboard Billing and Collections Dashboard

Support

Submit a support ticket

The Nue Platform

System Settings Platform Settings Lifecycle Manager Settings Price Builder Settings Billing and Usage Settings Nue Security API Keys Roles and Permissions Export and Import Understanding Data Storage and Synchronization

Integrations

Nue on Salesforce Nue on Salesforce Permission Sets Stripe Integration DocuSign Integration QuickBooks Integration NetSuite Integration - ARM Connector Recognize Revenue via RightRev Calculate Taxes via Avalara Integration Calculate Taxes via Stripe Tax Webhooks Update Nue Integration User for Salesforce Integration Nue on Salesforce Layout Configurations NetSuite Integration v2023 NetSuite Integration Setup NetSuite Connector - Fields Mapping Streamlined E-Invoicing with Avalara ELR

Home

Tutorial/Integrations

Webhooks

Webhooks are a way for different applications or services to communicate with each other in real-time. In simple terms, a webhook is a method of sending automated notifications or data from one application to another whenever a specific event or trigger occurs.

Here's how it typically works: One application sets up a webhook by specifying a URL endpoint where it wants to receive data. When a particular event happens in the source application, such as a new order placed or a form submission, it sends a POST request containing relevant information to the specified URL. The receiving application, or webhook listener, then processes this incoming data and takes appropriate actions based on the payload it receives.

Webhooks are commonly used to enable integrations between different systems, allowing them to exchange data in a timely manner. They are often employed in scenarios such as real-time notifications, data synchronization, triggering actions or workflows, and updating information across multiple platforms.

Compared to traditional polling or manual data retrieval methods, webhooks offer a more efficient and proactive way of transmitting information between applications. They eliminate the need for constant polling by the receiving application and enable instant communication when events occur, facilitating streamlined and automated processes in various software ecosystems.

Terminology

Webhook Events

Webhook events refer to specific occurrences or triggers within an application that prompts the sending of data via a webhook. These events can vary depending on the objects and their functionalities. For example, events can be a new order being placed, a customer updating their information, and an invoice being created.

Nue currently support the following webhook events:

EVENT TYPE	DESCRIPTION
order.created	The event is raised when an order, including an order placed in Salesforce, or an order placed via self-service API, is created.
order.activated	The event is raised when an order, including an order placed in Salesforce, or an order placed via self-service API, is activated.
order.canceled	The event is raised when an order, including an order placed in Salesforce, or an order placed via self-service API, is canceled.
invoice.created	The event is raised when an invoice is created.
invoice.activated	The event is raised when an invoice is activated.
invoice.canceled	The event is raised when an invoice is canceled.
invoice.payment_processed	The event is raised when an invoice payment attempt succeeds.
invoice.refund_processed	The event is raised when an invoice refund attempt succeeds
invoice.paid	The event is raised an invoice payment status is marked as paid
invoice.refunded	The event is raised an invoice payment status is marked as refunded
invoice.written_off	The event is raised when an invoice has been written off or partially written off
credit_memo.created	The event is raised when a credit memo is created.
credit_memo.activated	The event is raised when a credit memo is activated.
credit_memo.canceled	The event is raised when a credit memo is canceled.
credit_memo.applied	The event is raised when a credit memo apply to an invoice or a debit memo
credit_memo.unapplied	The event is raised when a credit memo unapply from an invoice or a debit memo
billing_job.completed	The event is raised when a billing job is completed.
billing_job.completed_with_error	The event is raised when a billing job is completed with an error.
billing_job.failed	The event is raised when a billing job is failed.
price_tag.created	The event is raised when a price tag is created.
price_tag.deleted	The event is raised when a price tag is deleted.
price_tag.updated	The event is raised when a price tag is updated.
price_tier.created	The event is raised when a price tier is created.
price_tier.deleted	The event is raised when a price tier is deleted.
price_tier.updated	The event is raised when a price tier is updated.

Webhook Endpoints

Webhook endpoints are URLs provided by the receiving application where data is sent when a webhook event occurs. Essentially, an endpoint acts as a destination for the data being transmitted by the webhook. When setting up a webhook, the user registers the endpoint URL to a relevant event type. Nue processes the incoming data and performs the necessary actions based on the payload received.

Register Webhook Endpoints

For instance, you would like to create a mirrored invoice in an accounting system once a Nue invoice was activated. You can follow the steps below.

Navigating to Webhook Configuration

Login to Nue App
Click on Settings → In the Settings Search Box, search for 'Webhooks'

Register a Webhook Endpoint

Click "New Webhook Endpoint" button
Enter the name of the endpoint. For example, "Accounting System Integration"
Enter your Endpoint URL
- Endpoint URL is where the Nue events are sent to.
- To receive Nue events, the Endpoint URL must actively listen for these events and handle them appropriately. For instance, this can be achieved by employing an iPaaS tool as the webhook listener.
  
  In our scenario, we can establish the Endpoint URL using a trigger URL from an iPaaS platform, such as "https://4e540848-d17b-4a06-99c1-a36437f9d0b1.trayapp.io".
Select one or more event types to register the URL with
- Once registered, when any of the selected events raised, Nue will post the event with event payload to the Endpoint URL.
- In our case, you can add "invoice.activated" event to register the webhook URL with this event.
Click Save. Now your webhook endpoint is successfully registered with selected event types.

Handle Events in Your Application

Nue's webhook event payload contains the user ID of the event trigger, the timestamp when the event occurred, the type of event, and details about the associated resource.

In our case, the event type is "invoice.activated", and the resource information consists of the invoice record data as well as the invoice item records. The webhook listener located at the URL "https://4e540848-d17b-4a06-99c1-a36437f9d0b1.trayapp.io" will parse the invoice payload, perform data transformation, and initiate the creation of a mirrored invoice in the Accounting System by invoking the accounting API.

Example Payload

The following is an example payload of order.activated event:

{
    "order": {
        "id": "8014w000008ZoiHAAS",
        "tax": 0,
        "name": "Test",
        "poDate": null,
        "status": "Activated",
        "endDate": null,
        "ownerId": "0054w00000B2HZoAAN",
        "discount": 0,
        "orderACV": 3000,
        "orderTCV": 3000,
        "poNumber": null,
        "subtotal": 3000,
        "listTotal": 3000,
        "orderType": null,
        "customerId": "0014w00004AcEWWAA3",
        "grandTotal": null,
        "totalPrice": 3000,
        "createdById": "0054w00000B2HZoAAN",
        "createdDate": "2024-11-11T22:11:56.000+00:00",
        "description": null,
        "orderNumber": "00002058",
        "priceBookId": "01s4w000001fahYAAQ",
        "totalAmount": 3000,
        "__customerEx": "{\"id\":\"0014w00004AcEWWAA3\",\"name\":\"Canva UK\",\"accountNumber\":null,\"orderPrimaryContactEmail\":null,\"orderPrimaryContactPhone\":null,\"orderPrimaryContactName\":null,\"shippingStreet\":null,\"shippingCity\":null,\"shippingState\":null,\"shippingPostalCode\":null,\"shippingCountry\":null,\"entityUseCode\":null,\"billingStreet\":null,\"billingCity\":null,\"billingState\":null,\"billingPostalCode\":null,\"billingCountry\":null,\"taxExempt\":null,\"entityId\":null,\"timezone\":null,\"billingSettings\":{\"billCycleDay\":\"1st of Month\",\"billingPeriod\":\"Month\",\"billingStart\":\"2024-10\",\"billingTiming\":null,\"prorationEnabled\":null,\"paymentTerm\":\"Net 30\",\"hideZeroItems\":null,\"creditMemoMode\":null,\"termBasis\":null,\"revenueModelMapping\":null,\"splitBySalesAccount\":null,\"splitForMilestone\":null,\"specificPeriods\":null,\"groupingAttributes\":null}}",
        "billCycleDay": null,
        "activatedById": "0054w00000B2HZoAAN",
        "activatedDate": "2024-11-11T22:11:58.000+00:00",
        "billingPeriod": "Month",
        "entityUseCode": null,
        "paymentMethod": "ACH",
        "billingAddress": null,
        "discountAmount": 0,
        "orderStartDate": "2024-11-01",
        "paymentMethods": "ACH",
        "systemDiscount": 0,
        "billToContactId": null,
        "orderPlacedDate": "2024-11-11",
        "shipToContactId": null,
        "shippingAddress": null,
        "billingAccountId": "0014w00004AcEWWAA3",
        "lastModifiedById": "0054w00000B2HZoAAN",
        "lastModifiedDate": "2024-11-11T22:11:58.000+00:00",
        "subscriptionTerm": 12,
        "cancelOnPaymentFail": false,
        "shippingAndHandling": null,
        "subscriptionEndDate": "2025-10-31",
        "orderReferenceNumber": null,
        "systemDiscountAmount": 0,
        "companyAuthorizedById": null,
        "companyAuthorizedDate": null,
        "subscriptionStartDate": "2024-11-01",
        "totalAmountWithoutTax": 3000,
        "customerAuthorizedById": null,
        "customerAuthorizedDate": null,
        "isShippingAddressSameAsBilling": true
    },
    "assets": [],
    "contacts": [],
    "customer": null,
    "invoices": [],
    "entitlements": [],
    "orderProducts": [
        {
            "id": "8024w00000ZbDVKAA3",
            "sku": "pipedrive10_1724900663615",
            "tax": 0,
            "name": "0000009223",
            "uomId": "a0T4w00000rgGMOEA2",
            "entity": null,
            "status": "Activated",
            "assetId": "a0R4w000010iVnuEAE",
            "orderId": "8014w000008ZoiHAAS",
            "taxCode": "SW056003",
            "taxMode": null,
            "__uom_ex": "{\"id\":\"a0T4w00000rgGMOEA2\",\"name\":\"Each/Month\",\"decimalScale\":0,\"roundingMode\":\"Up\",\"quantityDimension\":\"Each\",\"termDimension\":\"Month\"}",
            "deltaACV": 3000,
            "deltaARR": 3000,
            "deltaTCV": 3000,
            "discount": 0,
            "entityId": null,
            "isChange": false,
            "lineType": "LineItem",
            "quantity": 250,
            "subtotal": 3000,
            "accountId": "0014w00004AcEWWAA3",
            "assetType": "Subscription",
            "autoRenew": false,
            "deltaCMRR": 250,
            "evergreen": false,
            "listPrice": 1,
            "productId": "01t4w00000PQs5jAAD",
            "sortOrder": 1,
            "changeType": "NewProduct",
            "totalPrice": 3000,
            "assetNumber": "SUB-004472",
            "createdById": "0054w00000B2HZoAAN",
            "createdDate": "2024-11-11T22:11:57.000+00:00",
            "description": null,
            "priceBookId": "01s4w000001fahYAAQ",
            "productName": "Pipedrive Documents",
            "totalAmount": 3000,
            "billCycleDay": null,
            "billingPeriod": "Month",
            "billingTiming": "In Arrears",
            "changeAssetId": null,
            "entityUseCode": null,
            "includedUnits": null,
            "netSalesPrice": 1,
            "actualQuantity": 250,
            "carvesEligible": false,
            "discountAmount": 0,
            "listTotalPrice": 3000,
            "systemDiscount": 0,
            "changeAssetType": "Subscription",
            "currencyIsoCode": null,
            "productOptionId": null,
            "billingAccountId": "0014w00004AcEWWAA3",
            "cancellationDate": null,
            "lastModifiedById": "0054w00000B2HZoAAN",
            "lastModifiedDate": "2024-11-11T22:11:58.000+00:00",
            "lifecycleEndDate": null,
            "priceBookEntryId": "01u4w00000R60aUAAR",
            "proratedQuantity": null,
            "subscriptionTerm": 12,
            "revenueContractId": null,
            "summaryLineItemId": null,
            "defaultRenewalTerm": 0,
            "lifecycleStartDate": null,
            "rootOrderProductId": null,
            "billCycleStartMonth": null,
            "shippingAndHandling": null,
            "subscriptionEndDate": "2025-10-31",
            "carvesRevenueSegment": null,
            "parentOrderProductId": null,
            "systemDiscountAmount": 0,
            "productOptionQuantity": null,
            "subscriptionStartDate": "2024-11-01",
            "totalAmountWithoutTax": 3000,
            "actualSubscriptionTerm": 12,
            "carvesLiabilitySegment": null,
            "contractRevenueSegment": null,
            "contractLiabilitySegment": null,
            "changeReferenceOrderProductId": null
        }
    ],
    "subscriptions": [
        {
            "id": "a0R4w000010iVnuEAE",
            "zoneId": "America/Los_Angeles",
            "endDate": "2025-10-31",
            "version": 1,
            "entityId": null,
            "quantity": 250,
            "termType": "Month",
            "accountId": "0014w00004AcEWWAA3",
            "assetType": "Subscription",
            "evergreen": false,
            "productId": "01t4w00000PQs5jAAD",
            "startDate": "2024-11-01",
            "taxAmount": 0,
            "priceModel": "Usage",
            "productSku": "pipedrive10",
            "totalPrice": 3000,
            "windowSize": "DAY",
            "assetNumber": "SUB-004472",
            "createdById": "0054w00000B2HZoAAN",
            "createdTime": "2024-11-11T22:11:58.000+00:00",
            "description": null,
            "productName": "Pipedrive Documents",
            "billCycleDay": null,
            "billingPeriod": "Month",
            "billingTiming": "In Arrears",
            "orderProductId": "8024w00000ZbDVKAA3",
            "billingAccountId": "0014w00004AcEWWAA3",
            "cancellationDate": null,
            "lastModifiedById": "0054w00000B2HZoAAN",
            "lastModifiedTime": "2024-11-11T22:11:58.000+00:00",
            "billCycleStartMonth": null,
            "delaySecondsForRating": 300
        }
    ],
    "changeOrderRequest": null,
    "linePriceDimensions": []
}

Troubleshoot and Resend Webhook Events

If you don't receive an expected response from registered endpoints, you can review the webhook event logs to examine the details of all events sent to the current endpoint. If there's a connection problem or the endpoint returns a failed response code, you'll notice the event marked as failed in the log.

To quickly find a specific event, you can search by resource ID or filter events based on status, event type, or date.

Additionally, if needed, you can resend an event to the endpoint URL by clicking Resend at the top right of the event response section. This action triggers Nue to resend a new event to the endpoint with the same content as the failed event.

Putting It Altogether

Webhooks serve as real-time communication channels between different applications or services, allowing them to exchange automated notifications or data when specific events occur.

Typically, one application configures a webhook by specifying a URL endpoint where it wants to receive data. When a predefined event happens in the source application, such as a new order or invoice being created, relevant information is sent in a POST request to the specified URL. The receiving application, or webhook listener, processes this data and takes appropriate actions based on the received payload.

Webhooks are commonly used for integrating different systems, facilitating real-time notifications, data synchronization, and automated workflows. Compared to traditional methods like polling, webhooks offer a more efficient and proactive way to transmit information, eliminating the need for constant checking and enabling instant communication upon event occurrence.

Nue supports various webhook events, including order and invoice-related actions, each triggering specific operations in the receiving application. Users can register webhook endpoints to receive these events, specifying the event types they're interested in.

For instance, to integrate Nue with an accounting system to create mirrored invoices upon activation, users can follow these steps:

1. Navigate to Webhook Configuration in the Nue App Settings.
2. Register a new webhook endpoint, providing a name and Endpoint URL.
3. Select the desired event types, such as "invoice.activated", for which the webhook URL should be notified.
4. Handle the incoming events in the receiving application, parsing the payload and initiating necessary actions, like creating mirrored invoices in the accounting system.

In case of issues with endpoint responses, users can troubleshoot by reviewing webhook event logs, searching or filtering events by various criteria, and resending failed events if necessary, ensuring smooth communication between applications.