Skip to main content
Build your endpoint to these rules. They are the contract KYC delivers against.

​
Your endpoint

  • Use HTTPS on port 443, with a certificate from a publicly trusted authority.
  • Use a public host name. KYC refuses private, internal and reserved addresses.
  • Don’t redirect. KYC never follows a redirect; a 3xx counts as a failure.
  • Verify every request. Check the signature, and reject a webhook-timestamp more than 5 minutes from your clock.

​
Responding

  • Respond with a 2xx within 10 seconds. Anything slower counts as a failure and is retried.
  • Respond first, then do the work. Store or queue the event, return 2xx, and process it afterwards.
  • Return 410 only when the endpoint is retired for good. KYC disables the endpoint straight away.
See Retries and auto-disable for what happens with each response.

​
Handling events

  • Expect duplicates. Delivery is at least once, so the same event can arrive more than once. Deduplicate on webhook-id, which is the same as data.id.
  • Don’t rely on order. Events can arrive out of order, especially after retries. Use data.occurredAt to sequence them, and discard anything older than what you already have.
  • Fetch details through the API. Payloads carry IDs and metadata only, never content or guest personal data.
  • Ignore what you don’t recognise. New fields, event types and enum values (such as a new channel) are added without notice. Your code must not fail on them.

​
Security

  • Keep your signing secret in a secrets manager, and never log it.
  • Treat webhook payloads like API data: they carry guest-related IDs. Follow the PII guidance.
  • If you set up a credential header with KYC, check it as well as the signature.