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