RoundPlanAPI reference
v1OpenAPI 3.1 ↗Get an API key

Getting started

Events and webhooks

When something changes, RoundPlan records an event. Your system can receive it as a webhook, a call to a URL of yours, or read it with GET /events.

Events

An event says what happened and to which object, never the object itself: read it from the API when you need it. That way an event never carries data your key could not read, and never carries a stale copy.

trip.createdA trip was created (a template turned into a trip counts too).
trip.status_changedIts status changed. data.from and data.to say from what to what.
trip.acceptedThe client accepted the proposal.
trip.publishedThe client page went live.
trip.unpublishedThe client page was withdrawn.
trip.updatedAnything else about the trip changed: title, dates, itinerary, travellers, page texts, or one of its options.
trip.deletedThe trip was deleted (or turned into a template).
payment.createdA payment was shown to the client. One still being prepared makes no event.
payment.paidA payment was paid in full.
payment.updatedSomething else about a payment the client sees changed.
payment.deletedA payment was cancelled or deleted, so the client no longer sees it.
contact.createdA contact was created.
contact.updatedA contact changed, or joined or left a trip.
contact.deletedA contact was deleted.
The three *.updated events are grouped: they are sent once the object has had no change for a minute, and at most five minutes after the first one. An agency editing an itinerary for half an hour sends a handful of events, not hundreds. The others are sent at once.

Webhooks

An owner adds a webhook in Settings → API: an https URL and the events it should receive. RoundPlan then sends each event as a POST with a JSON body, the event, and these headers:

  • RoundPlan-Signature: the signature to check (see Verifying webhooks).
  • RoundPlan-Event-Id and RoundPlan-Event-Type.

Answer with any 2xx within 10 seconds; do the work afterwards. Redirects are not followed.

Retries and ordering

A call that does not get a 2xx is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and then every 24 hours, for three days. A webhook that fails for three days in a row is switched off and the agency's owners get an email. Events can arrive more than once and out of order: deduplicate by the event id, and read the object from the API rather than trusting the order.

Catching up

Nothing is lost while a webhook is off or failing: GET /events keeps the last 30 days. Store its next_cursor and pass it as after to read only what is new.