Stage Trigger Post Webhook UI Guide

This article explains how to configure the Post Webhook action within a Stage Trigger in SalesNexus Powered by Nexi.

It is intended for users configuring webhook integrations inside the UI and outlines how each field works, what to enter, and how merge tags are resolved.

---

Overview

When a Stage Trigger fires, SalesNexus sends an HTTP request to the configured endpoint.

You can control the following fields:

• URL (required)
• Method
• Headers
• Payload
• Timeout

Both the URL and Payload support merge tags, which are resolved before the request is sent.

---

URL (Required)

The URL must include https://.

Merge tags are fully supported and can be used in:

• Path parameters
• Query strings

Examples

• https://hooks.example.com/opportunity-updated
• https://api.example.com/crm/salesnexus/event/[opportunity.title]
• https://api.example.com/webhooks/stage-change?email=[email]&owner=[user.email]

---

Method

This field is optional.

If left blank, the default method is:

POST

Supported values

• POST
• PUT
• PATCH

---

Headers

This field is optional.

Headers must be entered as a valid JSON object.

Example

{
  "Authorization": "Bearer YOUR_TOKEN",
  "X-Source": "SalesNexus",
  "Content-Type": "application/json"
}

Notes

• If omitted, the request will still be sent
• Default Content-Type is application/json if not specified
• Invalid JSON will be ignored

---

Payload

This field is optional and defines the request body.

If no payload is provided, SalesNexus sends the default system payload.

Default Payload Example

{
  "triggerId": 123,
  "action": "PostWebhook",
  "opportunity": {
    "id": 456,
    "title": "My Deal",
    "currentStageId": 12,
    "amount": 2500.00,
    "currency": "USD"
  },
  "contact": {
    "contactId": 789
  }
}

If a custom payload is provided, SalesNexus sends exactly what is configured after merge tags are resolved.

---

Timeout

This field is optional.

Default:
5000 ms

Limits

• Minimum: 1000 ms
• Maximum: 30000 ms

Values outside this range are automatically adjusted.

---

Merge Tag Support

SalesNexus supports two merge tag formats:

• [token]
• {{token}}

Examples

• [first_name]
• [opportunity.title]
• [user.email]
• {{contact.phone}}

---

Supported Fields

Merge tags can be used from the following data sources:

• Contact fields
• Opportunity fields
• User fields

---

Contact Fields

Standard fields

• [first_name]
• [last_name]
• [full_name]
• [email]
• [phone]

Prefixed format

• [contact.first_name]
• [contact.email]
• [contact.phone]

Custom fields

Custom fields are supported using the field name:

• [annual_revenue]
• [lead_source]
• [favoriteproduct]

Matching rules

• Case insensitive
• Non-alphanumeric characters are ignored

Example:
“Annual Revenue” can be referenced as [annual_revenue]

---

Opportunity Fields

Standard fields

• [opportunity.title]
• [opportunity.amount]
• [opportunity.currency]

Custom fields

• [opportunity.deal_source]
• [opportunity.next_step]
• [opportunity.contractvalue]

---

User Fields

• [user.name]
• [user.username]
• [user.email]
• [user.title]
• [user.company]
• [user.phone]
• [user.profileImageUrl]
• [user.profileImage]

Note: In this context, user.* refers to the automation runtime user and may not always match the opportunity owner.

---

Unsupported Syntax

Do not use the following formats:

• [field:Custom Name]
• [Opportunity Title] (spaces inside brackets)
• [contact:first_name]

These formats are not supported and may not resolve correctly.

---

Best Practice: Writing a Payload

Always use valid JSON when possible.

Recommended Example

{
  "event": "opportunity_stage_trigger",
  "contact": {
    "firstName": "[first_name]",
    "lastName": "[last_name]",
    "email": "[email]",
    "phone": "[phone]"
  },
  "opportunity": {
    "title": "[opportunity.title]",
    "amount": "[opportunity.amount]",
    "currency": "[opportunity.currency]"
  },
  "user": {
    "name": "[user.name]",
    "email": "[user.email]"
  }
}

---

Example Integration

URL

https://hooks.example.com/workflows/opportunity-stage-change

Method

POST

Headers

{
  "Authorization": "Bearer YOUR_TOKEN",
  "Content-Type": "application/json"
}

Payload

{
  "source": "salesnexus",
  "type": "stage_trigger",
  "contact": {
    "name": "[full_name]",
    "email": "[email]"
  },
  "opportunity": {
    "title": "[opportunity.title]",
    "amount": "[opportunity.amount]",
    "currency": "[opportunity.currency]"
  },
  "owner": {
    "name": "[user.name]",
    "email": "[user.email]"
  }
}

---

Troubleshooting

Check the following if your webhook is not working:

• URL begins with https://
• Headers are valid JSON
• Payload is valid JSON
• Merge tags use supported syntax
• No unsupported formats like [field:Name]
• Authentication is included if required
• Timeout increased for slow endpoints (up to 30000 ms)

---

Key Behavior Notes

• Unknown merge tags resolve to an empty string
• Missing contact data may result in raw values being sent
• Non-2xx responses are treated as failures and may trigger error notifications