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 customer created the event is raised when a customer is created in nue, including synced from salesforce, or created via self service api customer updated the event is raised when a customer is updated in nue, including synced from salesforce, or updated via self service api customer deleted the event is raised when a customer is deleted in nue, normally via self service api customer first order placed the event is raised when a customer has the first order placed, including the order synced from salesforce, or created via self service api 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 subscription updated the event is raised when fields are updated on a subscription, currently supporting autorenew or custom fields this event will not be raised when a subscription undergoes versioning through a change order 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 https //app nue io click on settings → in the settings search box, search for 'webhooks' webhook list jpg 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 https //4e540848 d17b 4a06 99c1 a36437f9d0b1 trayapp io/ " set authorization token (optional) the default authorizaiton token will be included as a nue secret token header in all webhook requests, allowing your endpoint to verify the authenticity of incoming events from nue optionally, you can set up additional custom headers by clicking the "add additional header" button 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 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 , event log jpg 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