Events and deliveries
Register an HTTPS endpoint in the Partner Portal and receive the twelve partner events, with their fields, Send test, deliveries and retries.
Webhooks tell you what happened after a push: imports, failures, removals, connection changes, moderation, expiry and key expiry.
Endpoints#
A partner admin adds endpoints in the Partner Portal under Integration › Webhooks:
- the URL must be a public
https://URL on port 443 (up to 2,048 characters); private and local addresses are refused; - pick the events to receive (at least one);
- an optional description (up to 80 characters).
On save, the Partner Portal shows the endpoint's signing secret once — copy it then; it won't be shown again. See Verifying signatures.
Common fields#
Every delivery body is a JSON object that wraps the event:
{ "event": "<type>", "data": { … }, "timestamp": <Unix seconds> }event repeats the event type (also in the X-NK-Event header) and timestamp is the signing time (also in X-NK-Timestamp). The event itself is data:
| Field | Meaning |
|---|---|
data.id |
the event id — deduplicate on data.id |
data.type |
the event type below |
data.created_at |
when the event happened, RFC 3339 UTC |
data.environment |
sandbox or live |
data.connection_id |
the connection (null for key and test events) |
plus, inside data and depending on the event, external_id, listing_id, public_url, batch_id, failure_code, details and status. Events never carry agency-internal ids or personal data beyond what you sent.
{ "event": "item.imported", "timestamp": 1760256000,
"data": { "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9b0e4c1a77", "type": "item.imported", "created_at": "2026-10-12T08:00:00.000Z",
"environment": "live", "connection_id": "9b1d6c2e-4f3a-4c8e-9a71-2d5e8f0b3c44", "external_id": "REAA-12345",
"listing_id": "…", "public_url": "https://novikvadrat.rs/…", "status": "active", "details": { "warnings": [] } } }Every field in the table below sits inside data.
The twelve events#
| Event | Fires when | Extra fields |
|---|---|---|
connection.status_changed |
redeem (certifying), certify (active), pause by the agency or staff, resume (active), revoke |
status, details: { by, reason } |
connection.certification_rejected |
staff send a certifying connection back | status: "certifying", details: { note } |
batch.completed |
every item of a batch reached a final state | batch_id, details: { counts } |
item.imported |
the worker published, paused or updated the listing | external_id, listing_id, public_url, status (the listing's), details: { warnings } |
item.validated |
a sandbox item passed every check | external_id, details: { warnings } |
item.failed |
an item ended failed | external_id, failure_code, details |
item.review_required |
the duplicate rule held an item on an active connection | external_id, failure_code: "duplicate" |
item.removed |
a removal or a reconcile removal took effect | external_id, listing_id, status (sold, rented, deleted or expired) |
listing.moderation_changed |
staff moderation changed a listing you manage | external_id, listing_id, status (the new moderation status: approved, pending, rejected or removed), details: { previous } (the moderation status before the change) |
listing.expired |
a listing expired after 60 days without a push | external_id, listing_id |
key.expiring |
30 days before one of your keys expires | connection_id: null, details: { key_id, expires_at } |
webhook.test |
Send test in the Partner Portal | connection_id: null; common fields only |
Items that answer needs_review on a certifying connection fire no item.* event: the batch result already says it.
Send test#
Send test on an endpoint queues one webhook.test event to that endpoint: "Test queued. It's delivered within a minute."
Deliveries and retries#
Events are delivered by a dispatcher that runs every minute. A delivery succeeds on a 2xx answer. A failed delivery is retried after 2, 10, 60 and 600 seconds; the fifth failed attempt is dead-lettered (about 11 minutes after the first). An endpoint that is down for longer loses the event, so read the reconcile view after an outage. Deliveries on an endpoint shows each attempt: time, event, status (Delivered, Retrying, Failed), attempts, the last response code and the first 500 characters of the response body.
Answer 2xx quickly and do the work afterwards; deliveries can arrive more than once and out of order, so deduplicate on data.id.
Last updated