Skip to main content
Webhooks send an HTTP POST request to a URL on your server whenever an event happens in your account, such as a chat request completing, an agent changing, or your credits running low. Use them to sync data, trigger workflows or alert your team without polling the API.

How it works

  1. You register an endpoint URL in the console and choose which events it receives.
  2. When one of those events happens, ReyGrid sends a JSON payload to your URL.
  3. Every request is signed with your endpoint’s secret, so you can verify it really comes from ReyGrid.
  4. Your server replies with a 2xx status within 10 seconds. Anything else is treated as a failure and retried.

Set up an endpoint

1

Create a route on your server

Add a POST route that accepts a JSON body and returns 200 quickly. Read the raw request body: you need it to verify the signature.
2

Add the endpoint in the console

Open Console → Webhooks, select Add endpoint, enter your URL and pick the events you want.
3

Save the signing secret

After creating the endpoint you see its signing secret (whsec_…) once. Store it in your server’s environment, for example REYGRID_WEBHOOK_SECRET. You can reveal or rotate it later from the endpoint card.
4

Send a test event

Select Send test on the endpoint card. ReyGrid sends a ping event and shows the response status in Recent deliveries.

A minimal receiver

Request format

Every delivery is a POST with a JSON body and these headers: The body is an event envelope:

Delivery and retries

  • A delivery succeeds when your endpoint answers with a 2xx status within 10 seconds.
  • Redirects are not followed: a 3xx response counts as a failure, so point the endpoint at the final URL.
  • Failed deliveries are retried after 30 seconds and again after 5 minutes, up to 3 attempts in total.
  • Every attempt, with its status code and duration, appears under Recent deliveries in the console for 30 days.
Deliveries are at-least-once and may arrive out of order. Make your handler idempotent: store processed event IDs and skip any id you’ve already handled.

Endpoint requirements

You can turn an endpoint off without deleting it with the switch on its card. Disabled endpoints receive nothing until you turn them back on.

Next steps

Events

Every event type and its payload.

Verifying signatures

Check that requests really come from ReyGrid.