Developers Guide

Learn how to manage API keys and webhooks using the Developers settings. This guide covers setup, security best practices, and test workflows.

Open Developers SettingsAdmin only

Overview

The Developers settings page lets you create and manage API keys and webhook subscriptions for integrations.

API Keys: create, revoke, rotate, and track usage.
Webhooks: create HTTPS endpoints, manage event types, and send test deliveries.
Security: keys are shown once; verify webhook signatures when using shared secrets.

API Keys

Go to Settings → Developers.
Provide a descriptive name and click Create API Key.
Copy the plaintext key immediately and store it securely.
Use the Rotate action to issue a new key; the old key is revoked.
Use the Revoke action to disable a key permanently.

Example HTTP usage

curl -H "Authorization: Bearer psk_..."   https://api.popiasafe.com/v1/resource

Webhooks

Enter your HTTPS endpoint URL and event types (comma separated).
Optionally set a shared secret; verify signatures on delivery.
Use Send Test to dispatch a sample payload and confirm your handler.
Monitor delivery success rate and timestamps in the list.

Sample JSON payload

{
  "id": "uuid",
  "type": "developers.test",
  "sentAt": "2024-12-01T12:00:00Z",
  "organizationId": "uuid",
  "source": "developers.test",
  "data": { "message": "PopiaSafe test webhook" }
}

Verify signature headers:

X-PopiaSafe-Signature: <hex hmac-sha256>
X-PopiaSafe-Timestamp: <unix-seconds>

Best Practices

Use distinct keys per environment and service.
Rotate keys periodically and after suspected leaks.
Retry failed webhook deliveries with exponential backoff.
Validate HTTPS certificates; never use plain HTTP.