Skip to content
4Fleet

Create an API key and test a webhook

Create a least-privileged API key, store its one-time secret, add a signed webhook endpoint, and verify a test delivery.

How-to · 12 min · Operators · Reviewed 30 Jul 2026

Goal

Create one scoped integration credential and prove that a signed test.ping webhook reaches the intended endpoint.

Prerequisites

  • You are the company owner. API key and webhook management are owner-only.
  • The active subscription includes API access and webhooks.
  • You have a secure secret manager. Do not store keys or webhook secrets in source control.
  • Your webhook receiver uses a public HTTPS URL and can preserve the raw request body for signature verification.

Steps

  1. Open Settings > Developer and review API Docs for the endpoints your integration needs.
  2. Under API Keys, select Create API Key.
  3. Enter a name that identifies the environment and owner, such as "Production dispatch sync".
  4. Select only the required read or write scopes, then select Create Key.
  5. Copy the plaintext key immediately into your secret manager. It is shown once and cannot be retrieved later.
  6. Make a read-only test request to an allowed endpoint using the X-API-Key header. Confirm that a scope you did not grant is rejected.
  7. Under Webhooks, select Add Endpoint.
  8. Enter the public HTTPS Endpoint URL, optional description, and the minimum event set, then select Create Endpoint.
  9. Copy the signing secret immediately. Verify incoming X-Webhook-Signature values against the raw request body before trusting any payload.
  10. On the endpoint row, select Send test ping. Open its delivery log and confirm that the test.ping delivery succeeds at the receiver.

Expected result

The API key can call only its granted scopes, the secret exists only in secure storage, and the webhook delivery log confirms a verified test.ping response.

Troubleshooting

  • Developer features are gated: the active plan does not include api_access or webhooks. Review Finance before retrying.
  • The key is lost: revoke it and create a replacement. The plaintext value cannot be displayed again.
  • An API request returns forbidden: confirm the X-API-Key header, active key, expiry, endpoint, and required scope.
  • The webhook URL is rejected: use a safe public HTTPS target. Local, private-network, loopback, and otherwise unsafe targets are blocked.
  • Signature verification fails: verify the raw body before JSON transformation and use the current endpoint secret.
  • The test remains pending or fails: inspect the delivery attempts, receiver status code, timeout, TLS, and endpoint logs before sending live events.

Related articles

Was this article helpful?