Send Koast events to your server

A webhook sends an event to a URL you own the moment something happens in Koast, so your own systems can react without asking Koast over and over. You add the endpoint in Settings. Your developer writes the code that receives it.

Before you start

• Webhooks need an Agency plan with an active subscription.
• Only the organization owner and admins can see and manage webhooks.
• You need an HTTPS address that accepts a POST, like https://hooks.fernhill.example/koast. Koast doesn't follow redirects, and it refuses private and local network addresses.
• Your organization can have up to 20 endpoints.

Add an endpoint

1. Open Settings and pick API & Webhooks

   API & Webhooks sits under General. The Webhooks section is below your API keys. Select Add webhook.

2. Add the URL

   Paste the HTTPS address your server listens on into Endpoint URL.

3. Pick the events

   Choose the events this endpoint should receive. See the list below.

4. Pick the brands

   By default an endpoint gets events from every brand in your organization. Pick brands to get only theirs.

5. Save and copy the signing secret

   Koast creates a signing secret for the endpoint. It starts with whsec_. Your server uses it to check that each event really came from Koast. Give it to your developer.

6. Send a test event

   Open the endpoint's menu and select Send test event to check your server answers. Koast sends a ping event, and the attempt shows up in the delivery log.

The events you can pick

Koast checks ad review and delivery status every 15 minutes, so ad.approved, ad.rejected and delivery.status_changed can arrive up to about 15 minutes after the change. Each event carries the full object, so your server doesn't need to call Koast back.

Keep the signing secret safe

• See the secret again. Select Reveal signing secret in the endpoint's menu whenever your developer needs it.
• Rotate it with Rotate signing secret if it may have leaked. The new secret takes over straight away, and the old one keeps working for 24 hours, so your server has time to switch. During those 24 hours each event is signed with both. Rotating again within the 24 hours doesn't cut the older secret short.

Read the delivery log

Select View deliveries in the endpoint's menu. Each endpoint has a delivery log with every attempt from the last 30 days: the event, whether it succeeded, the response code your server sent back, how long it took, and which attempt it was. A response from your server counts as a success only when its status is 2xx.

When your server doesn't answer

• Koast retries. A failed delivery is tried again after 30 seconds, then 2 minutes, 10 minutes, 30 minutes, 1 hour, and further apart after that, for about 3 days.
• The endpoint is turned off after 3 days of failures. Koast stops trying, marks the endpoint as disabled and emails the organization owner and admins with the address and the last error. If your server kept accepting other events in that time, the endpoint stays on and only the event that kept failing is dropped. It shows as failed in the delivery log, and Resend failed sends it again.
• Turn it back on with Enable in the endpoint's menu once your server is fixed. Then select Resend failed in the delivery log to send again the events whose last attempt failed, up to 100 at a time. Events of a type or a brand you've since removed from the endpoint aren't sent again.
• Your server may get an event twice. Your developer should ignore an event whose id they've already handled. Events can also arrive out of order.

You can also turn an endpoint off yourself with Disable. While it's off, Koast sends it nothing, and events that happen in that time aren't kept for later.

If your plan changes

If your organization leaves the Agency plan, you can still see and delete your endpoints, and turn them off. You can't add a new one or turn one back on until you're on an Agency plan again.