Owlat Docs

API Keys & Webhooks

Create API keys for programmatic access and set up outbound webhooks to receive real-time notifications for email and contact events.

Owlat provides API keys for programmatic access and outbound webhooks for real-time event notifications. Together, they let you integrate Owlat into your application stack — syncing contacts, triggering transactional emails, and reacting to email events like bounces and clicks.

API keys

Creating an API key

  1. Open Settings > Technical > API Keys.
  2. Click Create API Key.
  3. Give the key a descriptive name (e.g., "Production Backend" or "Staging Sync").
  4. Select the scopes (permissions) the key should have — at least one scope is required; keys are scoped to least privilege.
  5. Copy the key immediately — it won't be shown again.

Store your API key securely. Never commit it to source control, include it in client-side code, or share it in plain text. Use environment variables or a secrets manager.

Using your API key

Include the API key in requests to the Owlat API. See the API documentation for authentication details, available endpoints, and SDK options.

Common API use cases:

  • Creating and updating contacts from your application
  • Sending transactional emails (password resets, notifications)
  • Tracking custom events for automation triggers
  • Subscribing and unsubscribing contacts from topics programmatically

Managing keys

The key list shows when each key was last used (or Never used until its first call), so you can spot credentials that are safe to retire. For each key you can:

  • Rename — update the key's name in place without affecting the key itself.
  • Revoke — soft-disable a compromised or unneeded key. It stops working immediately but stays visible in the list with a Revoked badge.
  • Delete — permanently remove the key's row, including already-revoked keys. This cannot be undone.

Rotate your API keys on a regular schedule — even if they haven't been compromised. This limits the blast radius if a key is ever leaked.

Webhooks

Webhooks are outbound HTTP calls that Owlat sends to your server when events happen — like an email being delivered, a link being clicked, or a contact unsubscribing from a topic.

Setting up a webhook

  1. Open Settings > Technical > Webhooks.
  2. Click Create Webhook.
  3. Enter a name and your endpoint URL — the URL on your server that will receive the webhook payloads.
  4. Select the events you want to subscribe to.
  5. Save the webhook. The signing secret is shown once on creation — copy it immediately.

Available events

Owlat can notify you about these events:

EventFires when
email.sentAn email is sent
email.deliveredAn email is delivered
email.bouncedAn email bounces
email.openedAn email is opened
email.clickedA link in an email is clicked
email.complainedA spam complaint is received
contact.createdA new contact is created
topic.unsubscribedA contact unsubscribes from a topic

Subscribe only to the events you need. Processing unnecessary webhooks wastes resources on both sides.

Managing a webhook

Expand any webhook in Settings > Technical > Webhooks to:

  • Send Test — fire a sample test event at your endpoint to verify it is reachable (the webhook must be enabled).
  • Enable / Disable — pause deliveries without deleting the webhook.
  • Regenerate Secret — issue a new signing secret (the old one stops being valid).
  • Delivery Logs — inspect recent deliveries and responses (see below).

Delivery logs

Each webhook endpoint shows a delivery log so you can monitor:

  • Recent payloads sent to your endpoint
  • HTTP response status codes
  • Failed deliveries and retry attempts

If your endpoint is down or returning errors, webhooks will be retried automatically. Check the delivery log to diagnose issues.

Secret verification

Every delivery is signed with HMAC-SHA256 using the webhook's signing secret. Owlat sends the hex digest in the X-Signature header, along with X-Timestamp (Unix seconds) and X-Webhook-Id. Recompute the HMAC over the raw JSON body with your secret and compare it to X-Signature to confirm the payload came from Owlat and hasn't been tampered with. See the API documentation for verification code examples.

Always verify webhook signatures in production. Without verification, anyone who discovers your endpoint URL could send fake payloads.

Best practices

  • Use descriptive key names — "Production App v2" tells you more than "Key 1" when you're reviewing your keys six months later.
  • Separate keys by environment — use different API keys for development, staging, and production.
  • Monitor webhook delivery — check the delivery logs periodically to catch endpoint issues before they impact your integration.
  • Revoke unused credentials — remove old API keys and inactive webhook endpoints regularly.

Next steps

Next Feature flags