Webhook Provider Setup

A webhook provider lets MakerVera send a signed HTTP request to a URL you control whenever it needs to grant or revoke access. This works with any hardware or software that can receive webhooks—Raspberry Pi door controllers, ESP32 builds, self-hosted systems, or third-party platforms not yet natively supported by MakerVera.

This guide covers the admin side: creating the provider in MakerVera, protecting it with a signing secret, managing zones, and testing connectivity.

For the builder side—how to implement the receiving endpoint that validates and acts on MakerVera’s requests—see the Webhook Integration Guide.

Create the provider

1. Go to Settings → Integrations in your MakerVera admin panel.
2. Click Add Provider.
3. Select Webhook as the provider type.
4. Give the provider a display name (for example, “DIY door controller – basement”).
5. Fill in the URL fields. All fields are optional at creation, but at least one URL configuration must exist before grants can fire (see the tip below):

Field	What it does
Default grant URL	MakerVera posts here when granting access to any zone that doesn’t have its own URL
Default revoke URL	MakerVera posts here when revoking access from any zone without its own URL
User sync URL	MakerVera posts here when syncing user details (name, email) to your system
Probe URL	Used by the Test Connection button to verify your endpoint is reachable
Signature header	The HTTP header name MakerVera includes when sending the request signature. Defaults to X-MakerVera-Signature

6. Click Save.

Tip

You can also set a per-zone URL when you add zones (see Add zones below). A zone’s own URL takes priority over the provider defaults. If a zone has no URL and the provider has no defaults, grants will fail for that zone—so configure at least one level of URLs before going live.

Save your signing secret

When you save a new webhook provider, MakerVera generates a signing secret and displays it one time only. Your endpoint uses this secret to verify that incoming requests genuinely came from MakerVera.

• Click Copy to copy the secret to your clipboard, then store it securely (a password manager or your deployment’s secrets store).
• Click I have saved this secret to confirm and close the dialog.

Tip

Save the secret before closing this dialog. Once you close it, MakerVera won’t show the secret again. If you lose it, your only option is to generate a new one using the Rotate flow—which will break any endpoints still configured with the old secret until they’re updated.

Rotate the signing secret

You may need to replace the signing secret periodically—for example, if you suspect it has been exposed, or as part of a planned security rotation. Open the provider’s edit form and choose one of two options:

Rotate (immediate)

The old secret is invalidated the moment you confirm. Any endpoint still using the old secret will fail immediately. Use this when you can update all your receiving endpoints right away.

Rotate with grace window

MakerVera accepts both the old and new secrets for a period you choose: 1 hour, 24 hours, or 7 days. This lets you update your devices one by one without service interruption. Once all devices are updated, click End grace window now to stop accepting the old secret early—you don’t need to wait for the full window to expire.

After either rotation, MakerVera shows you the new secret in the same one-time display. Save it just as you did originally.

Tip

During an active grace window, the Test Connection button is temporarily disabled. The probe signs the request with the new secret, which doesn’t reflect whether your existing devices have been updated yet. Test Connection re-enables automatically once the grace window ends or you end it early.

Add zones

Unlike OpenPath (which syncs zones from the provider), webhook zones are created manually in MakerVera. Each zone represents a physical location or piece of equipment that your endpoint controls.

1. On the provider card, click Add Zone.
2. Fill in the zone details:

Field	Required?	Notes
Zone name	Yes	A label for this location, e.g. “Front door” or “Laser cutter room”
Webhook URL	Depends	Required if the provider has no default grant/revoke URLs set; optional if defaults are configured (leave blank to use the provider defaults)
Zone type	No	Door, Equipment, or Area—informational only, used for display and filtering

3. Click Save.

Repeat for each access point your endpoint manages.

Edit a zone

Click the edit icon on any zone row to update the zone name, webhook URL, or zone type. The zone’s internal identifier (included in the webhook payload sent to your endpoint) is assigned automatically when the zone is created and cannot be changed.

Delete a zone

You can delete a zone only when it has no active or scheduled access grants. If active or pending grants exist, the delete button is disabled and its tooltip shows the current grant count.

To delete a zone that has grants:

1. Revoke all active grants tied to that zone.
2. Cancel or wait for any pending scheduled tasks to complete.
3. Return to the zone and delete it.

When you delete an eligible zone, MakerVera asks you to confirm before removing it.

Tip

If you renamed or moved a physical access point, consider editing the existing zone rather than deleting and recreating it—editing preserves the zone’s history and avoids disrupting any active policies.

Test the connection

Click Test Connection on the provider card to send a probe to the configured Probe URL. A successful probe confirms that MakerVera can reach your endpoint and receive a valid response.

If no Probe URL is configured, the button is disabled—there’s nothing to test.

Troubleshooting

Grants are failing with a “no webhook URL” error

The zone or provider has no URL configured. Check that the failing zone has a webhook URL set, or that the provider has both a default grant URL and a default revoke URL. One of these must be in place before grants can fire.

Test Connection fails

• Confirm the Probe URL is correct and publicly reachable from the internet. MakerVera calls it from our servers, not from your local network.
• Confirm your endpoint returns an HTTP 200 response to the probe request.
• If your endpoint is behind a firewall or NAT, allow inbound HTTPS traffic from MakerVera’s servers. Contact support for the current IP range.

Signature verification is failing on your endpoint

• Confirm you’re reading the correct header. The default is X-MakerVera-Signature; if you changed the signature header name during provider setup, use that name instead.
• Make sure your endpoint is using the current signing secret. If you’ve recently rotated, confirm the new secret is deployed everywhere.
• During an active grace window, MakerVera sends requests with the new secret. Your endpoint should accept both the old and new secrets until the window closes.

The signing secret was lost before it was saved

Use Rotate (immediate) on the provider’s edit form. MakerVera generates a new secret and displays it once. Any existing endpoints will start failing immediately until they’re updated with the new secret—so be ready to update them promptly.