> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmembrane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External Events

External events let you get notified about things that happen in an external application.

<Callout icon="ℹ️" theme="info">
  External Events are connector-level interfaces. To change them, you need to modify the
  [Connector](/reference/workspace-elements/connectors) that implements a given data collection.
</Callout>

<Callout icon="🧪" theme="warning">
  As an alternative, you can define stand-alone [External Event
  Types](/reference/workspace-elements/external-events/external-event-types) directly in your workspace — useful when
  you want to subscribe to events without modifying (or even thinking about) a connector. This feature is currently
  experimental.
</Callout>

Each event type has:

* Name
* Parameters (optional)
* Payload schema

Events are located in the `events` folder of the connector. Each event has its own folder named `events/<event-key>` (for example, `events/user-created`).

## Event Specification

The event specification is located in the `spec.yml` file in the event folder. It has the following format:

```yaml theme={null}
name: Task Created
implementationType: webhook
parametersSchema:
  type: object
  properties:
    projectId:
      type: string
      description: ID of the project to monitor for new tasks
  required:
    - projectId
schema:
  type: object
  properties:
    id:
      type: string
    title:
      type: string
    description:
      type: string
    status:
      type: string
methods:
  subscribe:
    implementationType: javascript
  unsubscribe:
    implementationType: javascript
```

Let's break it down:

| Property             | Description                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | Human-readable name of the event that will be shown in the UI                                                                                                             |
| `implementationType` | Type of event implementation. Can be `webhook` or `global-webhook`                                                                                                        |
| `parametersSchema`   | JSON Schema describing parameters that need to be provided when subscribing to the event. In the example above, we require a `projectId` to know which project to monitor |
| `schema`             | JSON Schema describing the event payload structure that will be received when the event occurs                                                                            |
| `methods`            | Object describing implementation methods for the event. The list of methods depends on the `type` of the event.                                                           |

## Implementation Types

### Webhook

This event implementation type uses webhook subscriptions to get events.

When an event subscription is created, it registers a webhook and handles incoming payloads. When an event subscription is deleted, it unsubscribes from the webhook.

It optionally supports a refresh mechanism to keep the subscription active if the external app requires it.

Full article: [Webhooks](/reference/workspace-elements/external-events/webhook)

### Global Webhook

This event implementation type uses [Global Webhooks](/reference/workspace-elements/external-events/global-webhook) to get events.

Full article: [Global Webhook](/reference/workspace-elements/external-events/global-webhook)