Webhooks overview
HTTP callbacks when Lancer finds jobs, submits proposals, or new rooms appear.
Lancer webhooks POST a JSON payload to your endpoint when something happens. There are two kinds, and knowing which one you need is most of the setup:
| Organization webhooks | Campaign webhooks | |
|---|---|---|
| Configured in | Settings, then Integrations, Webhooks tab | The campaign's Integrations tab |
| Events | suitable_job, unsuitable_job, bid_complete, lead.new | job.new only |
| Purpose | Notifications. Lancer already handled the event; you are being informed. | Control. In external mode, your system must respond by calling the Public API. |
| Fires for | Any campaign, any mode | External-mode campaigns |
Webhooks require an active paid subscription. Both kinds can also be managed by an AI agent through the MCP server (campaign_webhook_upsert and friends).
Setting up an organization webhook
Go to Settings, then Integrations, and open the Webhooks tab.
Click Add webhook, enter your HTTPS endpoint URL, and pick one or more events.
Subscribing to lead.new requires at least one Upwork bidder account connected to chat, since the event is sourced from your Upwork inbox.
Use the Test action to send a real sample delivery, then check the Activity tab to see the delivery record and your endpoint's response.
Campaign webhooks are created the same way from the campaign's Integrations tab, as part of the external mode setup.
What your endpoint must do
- Accept
POSTrequests with a JSON body. - Respond with any
2xxstatus within 10 seconds. Do slow work asynchronously after acknowledging. - Treat deliveries as at-most-once and deduplicate on the
X-Lancer-Delivery-Idheader if you retry-sensitive processing. Details in Delivery, security, and testing.
Deliveries are one-shot
Each event is delivered once, with no automatic retry. A failed delivery is recorded in the log and the webhook stays active for the next event. Acknowledge fast so you never miss one.