Sign up

Webhooks

Hear about deliveries, replies and new customers as they happen.

A webhook tells your own system when something happens in Goomzo, so it doesn't have to keep asking. Register a URL, choose the events it hears, and Goomzo sends each one there as it happens.

Requirements

  • A URL on https://, reachable from the internet.
  • To manage endpoints through the API, an API key with the webhooks.manage permission. In the dashboard, only the organization's owner and admins can.

Add an endpoint

  1. Open Settings → Webhooks and select New endpoint.
  2. Enter the URL that will receive events.
  3. Choose the events it hears. Choose at least one.
  4. Open the endpoint and select Send test event to check that your receiver works.

An organization can have up to 10 endpoints. Turn one off to pause it: its events wait and are sent when it's turned on again.

Requests

POST /v1/webhook-endpoints

Request syntax

{ "url": "<URL>", "events": ["<EVENT>"] }
PlaceholderDescriptionSample value
<URL>String. Where events are sent. https:// only.https://example.com/webhooks/goomzo
<EVENT>String. An event it hears.message.delivered

Example request

curl https://api.goomzo.africa/v1/webhook-endpoints \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/goomzo", "events": ["message.delivered", "message.failed"]}'

Responses

The answer includes the endpoint's secret, which you use to check signatures.

Answer quickly

Answer with any 2xx status within 15 seconds. Do the slow work afterwards, for example in a queue.

Anything else counts as a failure: another status, a timeout, or no answer. Redirects aren't followed, so use the final URL. A failed delivery is tried again after 5 seconds, 5 minutes, 30 minutes, then 2, 5, 10 and 10 hours, with a little randomness so retries don't all arrive at once. After 8 tries, about a day, it's marked failed. If you answer 429, 502, 503 or 504 with a Retry-After header, the next try waits at least that long.

The same event can arrive more than once, and events can arrive out of order. Use webhook-id to skip ones you've already handled, and the timestamps in data to tell which came last.

When an endpoint is turned off

Goomzo turns an endpoint off, and emails the organization's owner and admins, when:

  • it answers 410 Gone, which asks for no more events, or
  • every delivery to it has failed for 5 days.

Its events wait while it's off. Fix the endpoint, then turn it on again in Settings → Webhooks.

The delivery log

Open an endpoint to see its deliveries from the last 30 days: what was sent, how many tries it took, and what your server answered. Select one to see its full body and your server's response, and select Resend to send it again.

Through the API, list an endpoint's deliveries with GET /v1/webhook-endpoints/{id}/deliveries, and send one again with POST /v1/webhook-deliveries/{id}/resend.

Next steps

Last updated