Webhooks are here. In Settings › Developers of your seller dashboard you add a URL, pick from 20 events (offers, sales, transfers, invoices, auctions, etc.), and we send each event to that URL as a signed request the moment it happens.
What a webhook does for a seller
A webhook is a message we send to an address of yours whenever something happens on your account. Think of it as a notification for software: the email and the app tell you about a new offer, and a webhook tells your own systems at the same moment, so they can act on it without anyone opening the dashboard.
That tends to matter once a portfolio runs on more than one tool. A broker might post every new offer in the team chat, a larger seller might log each lead in their CRM, and a bookkeeper might want each paid invoice in the accounting software on the day it is paid. Each of those is one endpoint listening for the events it needs.
The 20 events you can listen to
You pick per endpoint which events it receives, grouped by what they are about. Leads and offers is usually the busiest group: lead.offer.sent says who made the offer (you, your negotiation agent or our team), and lead.offer.accepted includes until when the domain is held for the buyer, the payment deadline and, for a deal you set up yourself, the checkout link to send them.
| Group | Events | A typical use |
|---|---|---|
| Leads and offers | lead.created, lead.message.received, lead.offer.received, lead.offer.sent, lead.offer.accepted, lead.offer.rejected, lead.offer.withdrawn | Post new offers and buyer messages to your team |
| Domains | domain.sold | Mark the name as sold in your own inventory |
| Domain transfers | domain_transfer.created, domain_transfer.action_required, domain_transfer.completed, domain_transfer.cancelled | Send the auth code or set a .uk IPS tag the same day |
| Subscriptions | subscription.started, subscription.cancelled, subscription.finished | Follow lease-to-own and rental deals |
| Invoices | invoice.created, invoice.paid | Book payouts and fees in your accounting |
| Auctions | auction.started, auction.bid.received, auction.finished | Follow the bids as they come in |
Every event carries the domain's ID and name and the IDs of what it is about, such as the lead, the order or the invoice, plus what never changes afterwards: when it was created, how much an offer was, what the buyer wrote. A domain.sold event also says how the name was sold (buy now, auction, lease to own or rent).
Values that can change, like a domain's price, are left out on purpose, so an event you process an hour later never shows a stale figure. When you need the current state, it is one request to the Nameshift API with an API key from the same Developers page.
Adding an endpoint, step by step
- Open Settings › Developers in your seller dashboard and choose the Webhooks tab.
- Press Add endpoint and enter the URL that should receive the events, starting with https://.
- Pick the events. Each one shows an example of its data, so you can write the receiving code before the first real event arrives.
- Add custom headers if your receiver expects them (its own API key, for example), and set the timeout and the number of attempts, or keep the defaults of 10 seconds and 8 attempts.
- Save, then press Send test event to see the endpoint answer.
Each endpoint has its own event history: every event sent to it, the data it carried and each delivery attempt with the response your server gave, marked as automatic or manual. A delivery that failed can be retried from there with one click, once you have fixed whatever refused it.
Checking and answering each request
Each event arrives as a POST request with a JSON body holding its ID, type, timestamp and data. The request is signed following the Standard Webhooks specification, in the webhook-id, webhook-timestamp and webhook-signature headers, with the signing secret shown on the endpoint's page. The Standard Webhooks libraries check a signature in a few lines in most languages, so there is usually no cryptography to write yourself.
Your server answers with a 2xx status within the endpoint's timeout. When it doesn't, we retry the event automatically, several times over the following hours, up to the number of attempts you set. A retry carries the same webhook-id, so you can recognize an event you already handled and skip it.
If a secret has to change, Rotate secret gives the endpoint a new one. Events are then signed with both the old and the new secret for 24 hours, which leaves a day to update your receiver without missing an event.
Setting up your first endpoint
The webhooks sit next to your API keys. Open Settings › Developers in your seller dashboard, add one endpoint for the event you act on most (for many sellers that is lead.offer.received), and send it a test event to see the first request arrive.
