Webhooks

Prospero provides webhooks which allow you to receive HTTP push notifications whenever entities are created, updated, or deleted.

You can use webhooks to build integrations that respond to changes in real time, such as updating external systems, sending messages based on activity, or triggering automated workflows.

How does a Webhook work?

A webhook is an event-driven push integration pattern. The push is simply an HTTP POST request sent to the URL of your choosing. The request is automatically triggered by Prospero when data changes. See Webhook Payloads for an example of what data is sent in the request.

Your webhook client is a simple HTTP endpoint. It must satisfy the following conditions:

• It's available in a publicly accessible HTTPS, non-localhost URL
• It will respond to the Prospero webhook push with an HTTP 200 ("OK") response

If delivery fails (i.e., server unavailable, takes longer than 5 seconds to respond, or responds with a non-200 HTTP status code), Prospero will retry the delivery up to three times, with a backoff delay according to the following chart:

If a webhook client continues to be unresponsive over many push attempts, Prospero might disable the webhook, and it must be manually re-enabled.

For additional information on Webhooks, we recommend checking out Webhooks - The Definitive Guide from RequestBin.

Webhook Events

When the state of an entity changes, Prospero creates a webhook event that contains all the relevant information associated with that action, including the affected entity. Prospero currently supports the following webhook events:

Getting Started

You will first need to create a webhook endpoint (or "consumer") to be called by Prospero. This can be a simple HTTP server you deploy yourself, or a URL endpoint configured by a service such as Zapier.

Creating a Webhook consumer

You might consider using something like Cloudflare Workers (the platform Prospero is built on!), Netlify Functions, or Vercel Functions, which provide a straightforward way of deploying simple HTTPS endpoints.

Deploying a simple webhook consumer on Cloudflare Workers might look something like this:

Code
 
export default {
  async fetch(req, _env, ctx): Promise<Response> {
    // Parse the payload
    const payload = await req.json();
    const { type, createdAt, data, updatedFrom } = payload;

    ctx.waitUntil(async () => {
      // Do something amazing with the data received!
    });

    // Respond with an HTTP 200 to signal all good
    return new Response(null, { status: 200 });
  },
} satisfies ExportedHandler;

Creating a Webhook

Webhooks are owned by an Organization, meaning they will trigger for all webhook events the webhook is listening for that occur within an Organization.

To create a webhook, email [email protected] with:

• The URL of your webhook endpoint
• The webhook events you want to listen for

The Prospero team will set up your webhook and notify you when it's live.

Deleting a Webhook

To delete a webhook, email [email protected] with:

• The URL of the webhook you want to delete

The Prospero team will delete your webhook and notify you when it's deleted.

Webhook Payloads

Webhook event payloads have the following generic signature:

Code
 
interface WebhookEvent {
  /** A UUID identifying the webhook event */
  id: string;
  /** An ISO 8601 UTC timestamp */
  createdAt: string;
  /** The type of webhook event this is, i.e., 'event.created' */
  type: string;
  /**
   * The post-action state of the subject entity. For deleted entities, this
   * will be the state immediately prior to deletion
   */
  data: object;
  /**
   * Only present on 'x.updated' webhook events. An object containing the
   * previous values of all updated properties with JSON PATCH semantics
   */
  updatedFrom?: object;
}

For example:

Code
 
{
  "id": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2024-08-15T23:12:04",
  "type": "event.created",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2024-08-25T15:00:00Z",
    "lastUpdatedAt": "2024-08-25T15:00:00Z",
    "orgId": "00000000-0000-0000-0000-000000000000",
    "archived": false,
    "title": "Performance",
    "start": {
      "date": "2024-08-25"
    },
    "end": {
      "dateTime": "2024-08-25T15:00:00Z"
    },
    "details": "<p>On Sale Sep. 1</p>",
    "status": 1,
    "flag": true,
    "draft": false,
    "commentCount": 0,
    "locationIds": [],
    "projectsIds": [],
    "roleGroupIds": [],
    "roleIds": [],
    "groupIds": [],
    "personIds": [],
    "itemIds": [],
    "consumables": [],
    "tagIds": [],
    "fileIds": []
  }
}

For full schema definitions of the data object, refer to the API Reference for each entity type.