# Events

> The events Presence Orbit sends to Orbit Exchange when reviews, replies, feedback and review requests happen, what each one carries, the events it listens to from other satellites, and how delivery works.

Source: https://docs.bifrostorbit.com/presence/developers/events/

When something happens in Presence Orbit, such as a new review arriving from Google, it records an event and sends it to Orbit Exchange, the hub that connects Orbit's products. Other satellites react to them there, and Orbit shows them under **Exchange**.

Presence Orbit has no webhooks of its own. To receive these events in your own systems, an owner or admin sets up [webhooks in Orbit](https://docs.bifrostorbit.com/orbit/developers/orbit-webhooks/). To keep your own website current, read the [public reviews API](https://docs.bifrostorbit.com/presence/developers/reviews-api/); new reviews show there within about 5 minutes.

## What Presence Orbit sends

| Event | When |
| --- | --- |
| `presence.review.received` | A new review arrives from a review site, such as Google, Facebook or Trustpilot, or from an import |
| `presence.review.replied` | A reply to a review is published on the review site |
| `presence.feedback.received` | Someone gives private feedback on the review page, or answers a survey |
| `presence.request.sent` | A review request goes out by email, text message or WhatsApp. Reminders send no event |

Insights Orbit can count `presence.review.received` as **Review received** on a website's reports, with its location, review site and rating. Each site in Insights Orbit chooses whether to.

Presence Orbit also sends Orbit's inbox notifications through Orbit Exchange, as `notification.created`: new reviews, low ratings, replies waiting for approval or that failed, follow-ups assigned to someone, and mentions in a chat (`collab.mention`).

## The envelope

Every event has the same outer shape as events from Orbit's other satellites. Only `data` differs.

| Field | What it holds |
| --- | --- |
| `id` | A unique ID (UUID) for this event. Use it to spot duplicates |
| `type` | The event name, such as `presence.review.received` |
| `version` | The version of this event's `data` shape, `1` today. It only goes up for a change that could break a receiver |
| `time` | When it happened, in UTC |
| `source` | Always `presence` |
| `sequence` | A number that goes up with each event from your organisation |
| `tenant.organisationId` | Your organisation. The other `tenant` fields are `null` |
| `subject.resourceType` | `review`, `feedback` or `request` |
| `subject.id` | The ID of the review, feedback or request |
| `actor.type` | `user` for a reply someone on your team published, `system` for everything else |
| `actor.id` | The person's ID, or `null` for `system` |
| `data` | The details below |

### Review events

`presence.review.received` and `presence.review.replied` have the same `data`:

```json
{
  "reviewId": "6aee50892701b762d4918729",
  "locationId": "6aee50892701b762d491861c",
  "location": "Northwilds Oslo",
  "source": "google",
  "rating": 5,
  "recommends": null
}
```

`rating` is 1 to 5, or `null` on sites that only ask for a recommendation, such as Facebook; `recommends` is then `true` or `false`.

### Feedback events

`data` has `feedbackId`, `locationId`, `location` and `rating` (1 to 5, or `null`).

### Request events

`data` has `requestId`, `locationId`, `location` and `channel`: `email`, `sms` or `whatsapp`.

Events never carry review text, reviewers' or customers' names, email addresses or phone numbers.

## What Presence Orbit listens to

When an Admin switches on review requests for Travel Orbit, Commerce Orbit or Booking Orbit, Presence Orbit reads these events from Orbit Exchange:

| From | Asks for a review after | Cancels the request on |
| --- | --- | --- |
| Travel Orbit | `travel.booking.created`, `travel.booking.changed` | `travel.booking.cancelled` |
| Commerce Orbit | `commerce.order.fulfilled` | `commerce.order.cancelled`, `commerce.order.refunded` |
| Booking Orbit | `booking.appointment.completed` | `booking.appointment.cancelled`, `booking.appointment.noShow` |

The events carry no contact details. When it is time to ask, Presence Orbit fetches the name and email address for that one booking, order or appointment from the other satellite. See [Ask for reviews after trips and orders](https://docs.bifrostorbit.com/presence/everyone/requests-after-trips-and-orders/).

## Delivery

Events are sent at least once. Each one waits in Presence Orbit until Orbit Exchange accepts it. If Exchange can't be reached, Presence Orbit tries again after 2 minutes, then waits twice as long each time, up to 12 hours between tries, for 12 tries in all. After that the event is no longer sent. Because a try can succeed even when the answer is lost, the same event can arrive twice: use `id` to spot it.
