Plugin Troubleshooting

This guide walks through the most common plugin issues operators run into and how to fix them.

My plugin shows "Failing" status

This means recent webhook deliveries have errored. Open the install (Settings → Plugins → gear icon) to see what's wrong.

Steps

I'm not receiving any events

Possible causes, in order of likelihood:

1. Plugin is disabled. Check the status pill. Click Enable if it shows Disabled.
2. Plugin isn't subscribed to the event you expect. Different plugins subscribe to different events. Open the plugin detail page to see its webhook_subscriptions list.
3. The event isn't firing in your subaccount. Test by triggering the event manually (e.g., end a test ride for a ride.ended event).
4. Webhook endpoint is unreachable. Move to "My plugin shows Failing status" above.
5. Token was revoked. Rotate the token and provide the new one to the vendor.

A specific event is missing

If most events are arriving but one isn't:

• Check the event taxonomy in the plugin's manifest. If the event isn't in webhook_subscriptions, the plugin isn't listening to it.
• Some events are not yet wired into Levy core. The zone.entered, zone.exited, and zone.violation events are defined but not always emitted depending on which zones-tracking modules are enabled in your subaccount.
• For customer.kyc_completed, the event fires only when a KYC plugin is installed and actively writing back results — without a KYC plugin, no event is emitted.

Webhook signature verification fails (vendor side)

If you're a vendor and your endpoint rejects Levy's signatures:

• Check that you're verifying the signature in the correct format: X-Levy-Signature: t=<unix-ts>,v1=<hex-hmac>.
• The signed payload is ${ts}.${body} — note the dot separator and that body is the raw request body, not the parsed JSON.
• The signing secret is your plugin's per-install secret, available in your vendor dashboard for each install.
• Levy rejects timestamps older than 5 minutes; ensure your clock is in sync with NTP.

See Submitting a plugin — webhook endpoint for sample verification code.

Plugin's API calls are returning 401

The plugin's token is invalid. Reasons:

• The token was rotated recently and the 24-hour grace period has expired. Send the new token to the vendor.
• The install was uninstalled — the token is permanently revoked.
• The token format doesn't match lvy_plg_<install-prefix>_<random> — the vendor may be using a token from a different account.
• The plugin's subaccount ID doesn't match the resource's subaccount ID — the vendor is trying to read data from a subaccount that didn't install them. This is a hard block at the RLS layer, not configurable.

Plugin's API calls are returning 403

The plugin's token is valid but missing a required permission. The response body includes the missing scope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing permission: read:customers.pii",
    "required_scope": "read:customers.pii"
  }
}

You (the operator) can't grant new permissions to an installed plugin without reinstalling. If a vendor's manifest changes to add a new permission, you'll see a banner asking you to re-consent.

Billing — charge failed

If a monthly or usage charge fails:

1. Open Settings → Billing → Plugin invoices to see the failed invoice.
2. Check your payment method in Settings → Billing → Payment methods. Update it if expired.
3. Stripe retries automatically on its standard schedule (4 attempts over ~2 weeks). The plugin stays active during retries.
4. If all retries fail, the plugin is disabled (not uninstalled — your config is preserved). Update your payment method and re-enable.

Billing — disputed charge

If you file a chargeback through your bank, Stripe Connect handles the dispute on Levy's behalf:

1. Levy collects evidence from the plugin's audit log (events delivered, API calls made).
2. The vendor may also submit evidence.
3. Stripe makes the final decision per network rules.
4. If the dispute is upheld in your favor, both the vendor's share and Levy's platform fee are returned.

Contact support@levyelectric.com if you need help preparing dispute evidence.

Token leaked — what do I do?

Config change isn't applying

When you save a config change, it takes effect on the next event delivery — typically seconds to minutes. If you don't see the change reflected:

• Check that you actually clicked Save (the form should clear its dirty state).
• For OAuth-connected plugins, re-running OAuth from the configure screen forces a fresh token exchange.
• Check the audit log — every configure action is logged with the new config. If it's missing, the save didn't go through.
• For BigQuery / Snowflake, schedule changes apply on the next scheduled run, not immediately.

Plugin works for some rides but not others

Plugins are scoped per subaccount. If you have multiple subaccounts (e.g., one per city), you need to install the plugin separately in each. A plugin installed in Subaccount A won't process rides in Subaccount B.

What's next

• Configuring a plugin — for routine config changes
• Plugin billing — billing-specific issues
• FAQ — common questions and quick answers