Planned maintenance: Tue Dec 8, 11:30pm–12:30am ET (8:30–9:30pm PT / Wed 5:30–6:30am CET). Brief downtime possible (up to 15 minutes).

Status page
Skip to main content

How can we help?

Need help? Check out our documentation or contact support

Search

Webhook best practices

  • Updated

Build a reliable Bevy webhook receiver: check the shared secret, tell Bevy the delivery succeeded, finish heavy work after you reply, and make sure a second delivery of the same update does not create duplicate records or actions.

When Bevy sends a webhook, it posts data about a record change to a web address (URL) that your team controls. Your system must check that the request is real, tell Bevy it arrived safely, then apply the change in tools you care about (for example a CRM). Use this page as a checklist — whether you build the receiver yourself or work with a developer. Setup steps live in Configure webhooks. For how webhooks work at a high level, see Introduction to webhooks in Bevy.

Use a dedicated secure web address

Give Bevy one HTTPS URL that exists only to receive Bevy webhooks. That keeps webhook traffic separate from other website traffic.

  • The address must start with https:// (encrypted). Bevy does not allow plain http:// URLs.
  • Do not reuse a general website form or homepage URL for webhooks.

Verify the shared secret

A shared secret is a private password-like value that only Bevy and your receiver know. When Webhooks Secret Key and Webhooks Secret are set, Bevy sends that value in a request header (a named field on the request) with every webhook.

What to do:

  1. Read the header named in Webhooks Secret Key (default X-BEVY-SECRET; the name must start with x- or X-).
  2. Compare it to the value stored in Webhooks Secret.
  3. If they do not match, reject the request. Do not save or process the data.

Tip: Treat the secret like a password. Do not put it in public pages, shared chat, or ordinary logs. If it may have been exposed, change it in Bevy and in your receiver.

Reply quickly, then finish the work

After Bevy sends a webhook, it waits for a short reply that means “we got it.” That reply is separate from finishing the real work (updating a CRM, sending email, and so on).

Bevy reads the HTTP status code in your reply:

  • Success: any status below 400 (prefer 200 OK). Bevy treats the delivery as successful.
  • Failure: any status 400 or higher, a timeout (no reply in time), or a network error. Bevy will try again later.

Recommended order:

  1. Check the shared secret first.
  2. Save the incoming data to a queue or holding place for later work.
  3. Reply with 200 OK (or another status under 400) as soon as you have safely accepted the request.
  4. Do the slower business work after that reply.

Important: Do not reply with an error status (400 or higher) just to ignore a message. That tells Bevy the delivery failed, so Bevy will send it again. Prefer 200 after you have safely accepted the request — even if you will ignore or delay the business work.

Note: Bevy allows up to about 60 seconds for your reply. Reply well under that limit. Put slow CRM or database work in a queue instead of doing it before you respond.

Plan for retries

A retry means Bevy sends the same delivery again because your system did not reply successfully the first time (error status, timeout, or network problem).

For the usual one-record-per-request path:

  • Wait times grow after repeated failures — about 10, then 20, then 30 minutes, and so on.
  • After about 10 matching failed attempts, Bevy stops trying that delivery.
  • When Bevy retries, the data usually shows the current record in Bevy at send time — not a frozen copy from the first attempt. Someone may have edited the record in between.

Tip: Fix receiver errors quickly. Repeated timeouts or error replies use up Bevy’s retry attempts until Bevy stops sending that change.

Avoid duplicate work when Bevy sends the same update again

Idempotent means: if Bevy sends the same update (or a later version of the same record) more than once, your system ends up in the same correct state — it does not create a second CRM contact, send a second welcome email, or run the same action twice.

That matters because:

  • Failed deliveries are retried, so you may receive the same logical update more than once.
  • A later retry can include newer field values for the same record.
  • Two saves close together can also produce more than one webhook for one record.

What to do:

  • Match on the record’s stable ID in Bevy (and the update type), not on “this is the first time I saw this request.”
  • Update an existing row when the record already exists; create a new row only when it does not.
  • Keep a simple list of what you already processed (IDs and when) if you need to skip work you already finished.
  • Expect a delayed retry to show newer values than an earlier failed attempt.

Example: An attendee registers once. Your first attempt to save them fails, so Bevy retries. Your system should update that one attendee record — not create two attendees for the same person.

Which record actions produce a delivery is in When Bevy sends a webhook. Field-level shape is in Webhook payloads — this page does not include sample JSON.

One record per request vs bulk delivery

By default, Bevy sends one record per request. Some communities use bulk delivery, where one request can include more than one record of the same type. Bulk mode is not a setting in the Webhooks panel — if you receive multiple records in one request, ask Bevy Support whether bulk is enabled for your community.

  • Build (or ask your developer to build) so the receiver can handle both one record and many records in a request.
  • Reply that the request was accepted as soon as you have saved the whole message; do not make Bevy wait while you process every record one by one.

Log, watch for problems, and check the data

  • Keep records of incoming webhooks (without the secret), your reply status, and whether processing succeeded.
  • Set alerts when failures rise or work piles up in your queue.
  • Check that required fields are present before writing to other systems.
  • Protect your URL with normal security practices (HTTPS, firewall rules, rate limits). Bevy does not slow down how often it sends webhooks for you.

Quick checklist

Practice What to do
Secure URL Dedicated address; https:// only
Verify Match the shared secret before processing
Reply Return status under 400 after accept; prefer 200
Queue Do heavy work after you reply; respond within ~60 seconds
Retries Expect growing wait times; Bevy stops after ~10 matching failures
No duplicate work Update existing records; do not create duplicates on retry
Bulk Support may enable multi-record requests; handle either shape

Next steps

  1. Confirm URL, secret, and update types in Configure webhooks.
  2. Map triggers with When Bevy sends a webhook.
  3. Map fields with Webhook payloads.