Skip to content
Koffyr Documentation

Webhooks

Who this is for

Section titled “Who this is for”

Agency Owners who want to push Koffyr events to an external system — a CRM, a Slack bot, a custom workflow tool, or any HTTPS endpoint.

Before you start

Section titled “Before you start”

You need a publicly reachable HTTPS URL on a server you control. Koffyr delivers events via HTTP POST; the endpoint must respond with a 2xx status within 10 seconds.

Have a plan for storing the signing secret. Koffyr shows it once at creation — you cannot retrieve it again.

Step-by-step

Section titled “Step-by-step”

Create a webhook

Section titled “Create a webhook”
  1. Go to Settings → Webhooks.
  2. Click Add webhook.
  3. Enter your endpoint URL (must start with https://).
  4. Select the events you want to receive (for example, request.created, request.signing_completed).
  5. Click Save. Koffyr shows your signing secret — copy it and store it securely now. You will not be able to see it again.

Verify incoming deliveries

Section titled “Verify incoming deliveries”

Every request Koffyr sends to your endpoint includes an X-Valtio-Signature header. Use your signing secret to compute an HMAC-SHA256 digest of the raw request body and compare it to the header value. Reject deliveries where the values do not match.

Test a webhook

Section titled “Test a webhook”
  1. Open the webhook from Settings → Webhooks.
  2. Click Send test delivery. Koffyr sends a synthetic event to your endpoint.
  3. Check the delivery log below the settings to see whether the delivery succeeded.

View delivery history and replay

Section titled “View delivery history and replay”
  1. Open a webhook from Settings → Webhooks.
  2. The delivery log lists every outgoing delivery, its HTTP status, and the response body.
  3. Click Replay on any delivery to resend it immediately. Replay is useful when a previous delivery failed because your endpoint was temporarily unreachable.

Delete a webhook

Section titled “Delete a webhook”
  1. Open the webhook from Settings → Webhooks.
  2. Click Delete. All future deliveries for that webhook stop immediately.

What happens next

Section titled “What happens next”

When an event fires (for example, a request is sent or signing completes), Koffyr fans the payload out to every active webhook subscribed to that event type. Deliveries are attempted in the background; failures are logged and available for replay.

Troubleshooting

Section titled “Troubleshooting”

Deliveries are failing with a non-2xx status. Check that your endpoint is reachable over the internet, returns a 2xx within 10 seconds, and is not blocking Koffyr’s IPs.

Signature verification fails. Make sure you are computing the HMAC over the raw request body (before any JSON parsing) and comparing byte-for-byte to the header value. If you believe the secret is wrong, delete the webhook and create a new one to get a fresh secret.

I lost my signing secret. The secret cannot be recovered. Delete the webhook and create a new one to get a fresh secret; update your endpoint to use the new secret.

Section titled “Related”
  • Audit trail — webhook create/update/delete events appear in the audit trail

Last verified: 2026-05-27