Yirlo Webhooks: Send Replies and Hot Leads to Your Own Systems

What a Yirlo webhook sends

A webhook is an HTTPS endpoint on your side that Yirlo calls when something worth acting on happens in your campaigns. Two events are live today.

Both events arrive as a POST with a JSON body, so any server that can read JSON can handle them.

• reply.received: sent when a lead writes a genuine response. Vacation auto-responses, requests to stop emailing and outright refusals are skipped.
• hot_lead.received: a reply that Yirlo judged to be a hot lead, meaning the person showed real interest.

Add a webhook in Settings

In the app, visit Settings and pick Integrations. Enter your endpoint's URL and save it. An account holds at most 20 webhook URLs, and each one has to start with https.

Each webhook gets its own secret, a string that starts with whsec_. Copy it into your server's configuration or secret store. You need it to verify signatures, and a separate secret per webhook means you can give each receiving system only its own key.

Twenty URLs is enough to send the same event to several places. A common split is one endpoint for an internal alert service, one for a database writer and one for an automation tool, each with its own secret.

Sample webhook payload

Every delivery is wrapped in the same envelope: an event label, a timestamp in ISO 8601 under occurred_at, and a data object holding details about the lead and what they wrote. Here is a made-up hot_lead.received payload: {"occurred_at": "2025-03-12T14:07:31Z", "event": "hot_lead.received", "data": {"email": "[email protected]", "first_name": "Dana", "last_name": "Reyes", "company": "Northbridge Freight", "campaign": "Regional freight brokers", "reply": "Good timing. We are comparing tools this quarter. Could you send some times for a call next week?"}}

The data object carries six properties: reply, campaign, company, email, first_name and last_name. Whatever the lead typed back goes into reply, truncated at 3,000 characters, so a longer message will arrive clipped.

A reply.received delivery looks identical except for the event value. Use the event field to branch in your code, so one endpoint can handle both.

Verify the X-Yirlo-Signature header

Anyone who finds your endpoint URL can send it a POST. The signature lets you confirm a request came from Yirlo and that nobody changed the body on the way.

Every delivery is signed, which lets you check that it really came from Yirlo. On your side, run the same calculation on the body you received and check that your result matches the header.

The steps: read the raw request body as bytes before any JSON parsing, compute HMAC-SHA256 of those bytes with the whsec_ secret, then compare the result to the header with a constant-time function. If they differ, return a 401 and discard the request.

In Node, that is crypto.createHmac('sha256', secret).update(rawBody).digest('hex'), followed by crypto.timingSafeEqual on the two buffers. In Python, it is hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest(), followed by hmac.compare_digest. These examples use hex output. Send a test delivery to your endpoint, look at the header value, and match the digest encoding to what you see.

The most common cause of a mismatch is parsing the JSON first and then re-serializing it. Whitespace and key order change, and so does the hash. Sign-check the raw bytes, and parse afterward.

Respond fast and check delivery status

Your endpoint gets 5 seconds to respond to each delivery, and a handler that does slow work inline can miss that window. Once the signature is verified, reply with a 2xx status straight away and handle the heavy lifting afterward, for instance by placing the payload on a queue.

Each webhook in Settings, under Integrations, has its most recent delivery outcome shown beside it. If your receiving endpoint breaks, whether from a lapsed TLS certificate, a moved route or a bad deployment, check there first.

While you build, point a webhook at a temporary https endpoint that logs the raw body and headers. Once the signature check passes against real traffic, switch the URL to your production handler.

Connect Zapier, n8n or Make

Zapier, n8n and Make all connect to Yirlo today through their built-in webhook receivers. Each tool gives you a URL, and you paste it into Yirlo.

Zapier: begin a new Zap whose trigger is the Webhooks by Zapier app, using its Catch Hook event. n8n: use a Webhook node as the starting trigger. Make: open a new scenario and set Custom webhook as its first module. In each case, copy the generated URL and save it in Yirlo under Settings, then Integrations.

These tools receive the JSON fields as separate values, so email, company, campaign and reply can be mapped into later steps. If you want to verify the signature inside one of them, use a code step that has access to the raw body and your whsec_ secret.

What teams do with the events

Interested replies already reach you by email as hot leads. The webhook delivers the same moment to software, which is useful when a person should not be the first stop.

A company selling fleet software to regional freight brokers might send hot_lead.received to an internal alert service that pings the account owner at once. A team selling payroll tools to staffing agencies might send every reply.received to a database table and review reply volume by campaign each week.

Because each payload names the campaign, you can route by audience: replies from one campaign go to one owner, replies from another go to someone else. The reply text is included, so your own code can also tag, summarize or store it alongside your other records.

Questions

Related