MailKatana exposes two webhook surfaces on the public API binary:
  • outbound workspace webhooks that MailKatana sends to your endpoint URLs
  • inbound provider webhooks, including Stripe callbacks configured per workspace

​
Outbound webhook endpoints

Use the session-authenticated /v1/webhook-endpoints routes to manage where MailKatana delivers workspace events.
  • POST /v1/webhook-endpoints creates an endpoint
  • GET /v1/webhook-endpoints lists existing endpoints
  • PATCH /v1/webhook-endpoints/{endpointId} updates URL, status, description, or event filters
  • POST /v1/webhook-endpoints/{endpointId}/signing-secret rotates the signing secret and returns it once
  • POST /v1/webhook-endpoints/{endpointId}/send-test delivers a testing.testEvent payload immediately
Created endpoints default to disabled unless you explicitly set status to active.

​
Verifying outbound deliveries

Outbound webhook deliveries are signed with Standard Webhooks style headers:
  • Webhook-Id
  • Webhook-Timestamp
  • Webhook-Signature
When a signing secret is present, MailKatana computes the signature from the endpoint secret, webhook ID, timestamp, and raw JSON payload. Test deliveries send this payload shape: 
{
  "eventName": "testing.testEvent",
  "eventTime": 1714176000,
  "message": "test",
  "webhookSchemaVersion": "1.0.0"
}

​
Stripe integration setup

Use the session-authenticated /v1/settings/integrations/stripe routes to fetch or update workspace Stripe settings. The response includes:
  • enabled
  • has_signing_secret
  • webhook_url
  • supported_events
Enable the integration only after you store a Stripe signing secret.

​
Stripe webhook ingestion

Configure Stripe to send supported events to the webhook_url returned by the integration settings endpoint. MailKatana accepts callbacks at: POST /v1/integrations/stripe/webhook/{integrationId} That endpoint:
  • requires the Stripe-Signature header
  • validates the request against the stored signing secret
  • archives Stripe events by Stripe event ID for idempotency
  • normalizes only the supported Stripe events into MailKatana contact events
Unsupported event types and events that cannot identify a contact are archived and marked as ignored instead of failing the whole endpoint.

​
Supported Stripe events

Current supported Stripe event types are:
  • charge.dispute.created
  • charge.dispute.closed
  • checkout.session.async_payment_succeeded
  • checkout.session.async_payment_failed
  • checkout.session.completed
  • customer.created
  • customer.updated
  • customer.deleted
  • customer.subscription.created
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.trial_will_end
  • customer.subscription.deleted
  • invoice.paid
  • invoice.payment_failed
  • invoice.upcoming
  • quote.finalized
  • quote.accepted
  • quote.canceled