---
search:
  tags:
    - external-events
    - POST
seo:
  description: >-
    Bind an inbound provider event to a stage sub-step.… Reference for the POST
    /workspaces/{organizationId}/external-event-mappings endpoint in the Pile
    API.
sidebar:
  label: Create external event mapping
  badge: POST
title: Create external event mapping
type: openapi-operation
---
Bind an inbound provider event to a stage sub-step. source and stepKey slug-normalize; eventType is the provider's literal event name ("*" is a catch-all). The matcher resolves the payload at matchPath to the record's externalId (deal/customer) or externalRef (issue).

`POST /workspaces/{organizationId}/external-event-mappings`

**Request body** (`application/json`)

- `source` (string, required)
- `eventType` (string, required)
- `entityType` (string, required)
- `matchPath` (string, required) — Dotted path into the event payload resolving to the record's external id — e.g. "data.merchant\_id".
- `stepKey` (string, required)
- `secret` (string, required) — HMAC-SHA256 signing secret for this source's deliveries.
- `enabled` (boolean)

Request body example:

```json
{
  "source": "string",
  "eventType": "string",
  "entityType": "issue",
  "matchPath": "string",
  "stepKey": "string",
  "secret": "string",
  "enabled": true
}
```

**Responses**

- `201` — External event mapping created

Response example, 201:

```json
{
  "mapping": {
    "id": "string",
    "organizationId": "string",
    "source": "string",
    "eventType": "string",
    "entityType": "issue",
    "matchPath": "string",
    "stepKey": "string",
    "enabled": true,
    "createdBy": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```