Send Renr events to your app with webhooks

Webhooks let Renr push events to your own application the moment they happen, so you do not have to poll the API. When something occurs in your business — a contact is created, a task changes status, a message arrives — Renr sends an HTTP POST to a URL you control.

Create a webhook

1. Go to Developers → Webhooks and select Add Webhook.
2. Enter the Payload URL. This must be a public HTTPS endpoint that accepts POST requests.
3. Add an optional Description so you can tell several webhooks apart later.
4. Pick the events you want under Events to Subscribe. Use the search box to filter across every event, or tick a module heading to select all of its events at once.
5. Select Create Webhook.

Not sure what an event looks like? Select the code icon next to any event to preview its exact payload before you subscribe.

What Renr sends

Every delivery uses the same envelope, with the event-specific body under data:

{
  "event_type": "contact.created",
  "business_code": "your-business-code",
  "timestamp": "2026-01-13T12:00:00",
  "data": { }
}

Two headers accompany every request:

1. X-Renr-Signature — an HMAC-SHA256 signature of the raw request body, keyed with your webhook secret.
2. X-Renr-Delivery — a unique id for this delivery attempt. Store it and ignore repeats to make your endpoint idempotent.

Verify the signature

Always verify the signature before trusting a request. Your secret is on the webhook's Overview tab — treat it like a password and never commit it to source control.

const crypto = require('crypto');

const signature = request.headers['x-renr-signature'];
const payload = JSON.stringify(request.body);

const expected = crypto
  .createHmac('sha256', process.env.RENR_WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (signature === expected) {
  // request is authentic
}

Monitor deliveries

Open any webhook to see how it is performing. The tabs across the top give you:

1. Overview — success rate over the last 24 hours and 7 days, recent deliveries, and your signing secret.
2. Events — change which events the webhook subscribes to.
3. Deliveries — the full delivery history, filterable by status and by event.
4. Settings — the endpoint URL, description, and active toggle.

Select View on any delivery to inspect the exact payload Renr sent and the response your endpoint returned.

Retry a failed delivery

Failed deliveries are retried automatically up to three times with exponential backoff. If your endpoint was down longer than that, open the Deliveries tab and select Redeliver on the affected row. Renr resends the original payload byte for byte, so any signature or idempotency check on your side still lines up. The replay gets a fresh X-Renr-Delivery id and appears as a new row in the history.

Pause without deleting

Select Disable in the header to stop delivery while keeping the webhook, its secret, and its event subscriptions intact. Select Enable to resume. Use this during maintenance instead of deleting and recreating the webhook.

Troubleshooting

1. Nothing arrives — check the webhook is Active and that the event you expect is actually subscribed on the Events tab.
2. Deliveries show as failed — your endpoint must return a 2xx status within 5 seconds. Acknowledge first and process asynchronously.
3. Signature never matches — sign the raw request body exactly as received. Re-serializing the JSON changes the bytes and breaks the hash.
4. Duplicate processing — deduplicate on the X-Renr-Delivery header.

You need the Allow to use webhook feature permission under Developers to create or manage webhooks.