Webhooks

A webhook is your store telling an outside system that something happened. You give Brainerce an HTTPS endpoint and a list of events; when one of those events occurs, we POST it to your URL.

This is the opposite direction from an API key, which is an outside system asking your store for something. Most integrations need both.

Create a subscription

1. Go to Settings → Webhooks.
2. Click Create Subscription.
3. Enter the Endpoint URL. It must start with https://. A plain http:// address is rejected when you save, with an error rather than a warning. It must also be a public address on the internet: localhost, 127.0.0.1, and internal/private network addresses (anything on 10.x, 192.168.x, 172.16-31.x, or 169.254.x) are refused for the same reason, so you cannot point a webhook at a machine on your own office network. If the save fails on this step, the URL is the reason.
4. Add a Description so you can tell subscriptions apart later ("Production order handler").
5. Pick the events you want. Choose only the ones you'll act on; every extra event is traffic your endpoint has to absorb.
6. Create it, and save the signing secret immediately.

When customer.created fires: shopper signups now count

customer.created fires every time a new customer account appears, including when a shopper signs up on your storefront by themselves. That covers a normal storefront signup, a guest checkout that gets upgraded to a real account, a signup that went through email verification, and a "Sign in with Google"-style social signup, as well as a customer you add by hand in the dashboard.

This is a recent change, and it raises your event volume. Older stores' webhooks fired only when someone on your team created a customer in the dashboard, so shopper signups were invisible. If you built a handler back then and sized it for a handful of events a day, it now gets one per storefront signup as well. Nothing is resent: signups that happened before the change stay missed, so re-import that period from your Customers list rather than waiting for them.

Guest checkout does not fire it. A shopper who buys without registering gets a customer record, but no account and therefore no customer.created, so a CRM built only on this event will silently miss every guest. You still get those people on the order events: order.created and checkout.completed both carry the customer details. If your goal is "every buyer reaches my CRM", subscribe to an order event too, not just this one.

The same customer can trigger it more than once. A guest who bought months ago and now registers, or a customer you created by hand who later signs up on the storefront with the same email, both produce a customer.created carrying the customer id you already have. Treat the event as "create or update this customer id", never a blind create, or you will end up with duplicates.

The payload is deliberately small: the store id and the customer id, nothing else. It does not carry the customer's email, name, IP address, or the referral code they signed up with. Call the customers API with the id if you need the rest. That keeps personal data out of a POST to a third-party URL you may not control.

There is no separate "customer registered" event to subscribe to. If you are looking for one to tell a self-signup apart from a dashboard-created customer, it does not exist and cannot be added from this page: both arrive as customer.created and look identical. If that distinction matters to your system, record it on your own side at the point the shopper signs up.

The signing secret

You are shown the signing secret once, at creation. Save it before closing the dialog.

Use it to verify the HMAC-SHA256 signature on every webhook you receive. This matters more than it might sound: your endpoint is a public URL, so anyone who finds it can POST to it. Checking the signature is what tells you a request genuinely came from Brainerce and not from someone who guessed your URL.

If you lose the secret, use Rotate Secret to issue a new one. You'll see the new value once, on the same terms. Rotating invalidates the old secret, so update your endpoint promptly.

Watching deliveries, and how many times we retry

Each subscription shows its delivery record: how many succeeded, how many failed, the success rate, and when the last successful delivery was. Use Send test event to enqueue a test and confirm the wiring end to end, then check the delivery log a few seconds later.

Send test event sends a brand-new test event. It does not re-send a delivery that already failed.

Each event is tried 5 times over about 75 seconds, then given up on. The delays are 5, 10, 20 and 40 seconds after the first attempt. If your endpoint is down for longer than about a minute and a quarter, that event is gone. Nothing re-sends it later, and there is no way to replay a failed delivery from this page or from anywhere else. Plan for a way to re-import missed data from your orders or customers list if your endpoint has an outage.

When deliveries stop: Circuit Open

If your endpoint fails repeatedly, Brainerce stops sending and the subscription shows Circuit Open. It takes roughly two failing events in a row to get there, not ten or twenty: each event is retried 5 times, and 10 failed tries opens it.

This is a protection, not a punishment: it stops a dead endpoint from absorbing retries indefinitely. But it also means your integration is now silently receiving nothing, so it is worth checking this page when something downstream seems stale.

Everything that happens while the circuit is open is lost. Those events are never queued and cannot be replayed afterwards. When delivery resumes, it resumes from that moment and the gap stays a gap. If orders came in during the outage, re-import them from the Orders page rather than waiting for webhooks that will not arrive.

Does Circuit Open fix itself? After an hour, but it never sends the missed events

Yes, eventually, and only for new events.

An hour after the circuit opens, Brainerce tries again with the next event that comes in (and any others that arrive in the few seconds before that first one gets an answer, so expect a couple of deliveries, not exactly one). If your endpoint answers normally, the circuit closes and deliveries resume on their own. If it fails again, the circuit re-opens for another hour, and because the failure count is not reset while it waits, a single failed delivery is enough to re-open it. A broken endpoint therefore stays broken, retried about once an hour.

The events from the hour you missed are still gone. Recovery restarts delivery from that moment onward. It does not resend anything that happened while the circuit was open, and there is no way to replay those deliveries from this page or anywhere else. Re-import that period from your Orders or Customers list.

Don't wait for the hour if you have already fixed the endpoint. Fix it, then Deactivate and Activate the subscription. That resets the failure count too, so deliveries resume immediately rather than an hour later, and on a subscription that isn't one failure away from stopping again.

Deactivate or delete

• Deactivate stops delivery and keeps the subscription and its secret. Use this while you're fixing something.
• Delete removes it entirely.

Common problems

What's next?

• API keys and sign-in providers covers access in the other direction.
• Connect your storefront is the SDK path, which usually needs neither.