QuoteWerks Webhooks Documentation

Overview

QuoteWerks Webhooks allow you to receive real-time notifications when events occur in your QuoteWerks system. When an event happens (like a quote being accepted), the webhook system automatically sends an HTTP request to your specified URL with details about the event.

Getting Started

To create your first webhook:

1. Click the Add New button on the Webhooks page
2. Give your webhook a friendly Name (optional but recommended)
3. Select the event you want to listen for
4. Enter the URL where you want to receive notifications
5. Configure the HTTP method and body content
6. Click Save

Creating Webhooks

Basic Information

When creating a webhook, you'll need to provide:

Events

Events are organized by context (e.g., QuoteValet, QuoteWerks) and specific event name. The full event name follows the pattern: Context.EventName

Wildcard Events

Each context has a special *.ANY event that triggers for all events within that context. For example, QuoteValet.ANY will fire for QuoteValet.Accepted, QuoteValet.Viewed, and all other QuoteValet events.

Macros

Macros are placeholders that get replaced with actual values when the webhook fires. They use the format {{MacroName}} and can be used in URLs, headers, and the body.

System Macros

These macros are available for all events:

Event-Specific Macros

Each event type has its own set of macros based on the data available. When you select an event in the webhook editor, the available macros are shown in the macro search fields.

Using the Macro Inserter

Above each field that supports macros, you'll find a search box to find and insert macros:

1. Type in the search box to filter available macros
2. Click on a macro to insert it at your cursor position
3. Use Ctrl+M while in a field to jump to its macro search

HTTP Configuration

HTTP Methods

Body Content Types

Custom Headers

You can add custom HTTP headers to your webhook requests. Common uses include:

• Authentication: API keys, bearer tokens
• Identification: Custom headers to identify the source
• Routing: Headers used by the receiving system

Example Headers

Authorization: Bearer your-api-key-here
X-Webhook-Source: QuoteWerks
X-Tenant-ID: {{System.TenantAccountNumber}}

Body Templates

The body template defines what data is sent when the webhook fires. Click the magic wand button to generate a template with common macros for your selected event.

JSON Example

{
  "eventContext": "{{System.EventContext}}",
  "eventName": "{{System.EventName}}",
  "tenantAccountNumber": "{{System.TenantAccountNumber}}",
  "eventDateTime": "{{System.EventDateTime}}",
  "quoteValetDocumentID": "{{QuoteValet.Document.Headers.quoteValetDocumentID}}",
  "acceptedByName": "{{QuoteValet.Acceptance.AcceptedByName}}"
}

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <event>{{System.EventName}}</event>
  <tenant>{{System.TenantAccountNumber}}</tenant>
  <documentId>{{QuoteValet.Document.Headers.quoteValetDocumentID}}</documentId>
</webhook>

Testing Webhooks

Before relying on your webhook in production, you should test it to ensure it's configured correctly.

Using the Test Feature

1. Open the webhook you want to test (click the edit button)
2. Click the Test button in the modal
3. Review the pre-populated values - macros are replaced with sample data
4. Modify any values as needed for your test
5. Click Test to send the request
6. Check the Logs tab to see the result

Using webhook.site

webhook.site is a free service that provides a unique URL to capture webhook requests. It's perfect for testing:

1. Visit webhook.site
2. Copy your unique URL
3. Use this URL as your webhook destination
4. Test your webhook and view the results on webhook.site

Viewing Logs

The Logs tab shows the history of all webhook deliveries, including:

• Status: Success, Failed, or Pending
• Event: Which event triggered the webhook
• URL: The destination URL
• Response: HTTP status code and response body
• Timestamp: When the delivery was attempted

Filtering Logs

Use the filter options to narrow down the log entries by event, status, or URL.

Troubleshooting

Webhook Not Firing

• Ensure the webhook is enabled (toggle should be on)
• Verify the event name matches exactly
• Check that the tenant account number is correct

Receiving Errors

• Check the Logs tab for error details
• Verify the destination URL is accessible
• Ensure headers and authentication are correct
• Validate your JSON/XML body is well-formed

Macros Not Replaced

• Ensure the macro syntax is correct: {{MacroName}}
• Verify the macro name matches exactly (case-sensitive)
• Check that the event provides the data for that macro

Common HTTP Status Codes