EnterSignalGuide

Subscribe to Events

Creating a Subscription

Create a subscription to reliably integrate with EnterSignal’s unified Consumer Enterprise Facts data stream.

EnterSignal Subscriptions are meant to be unified and heterogeneous. So we expect you to create as few Subscriptions as possible to simplify integration, ideally one Subscription per environment.

curl -X POST https://api.entersignal.com/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{
    "name": "openai-chatgpt-staging",
    "filters": {
      "categories": ["*"],
      "fact_event_types": ["offer", "product", "announcement"],
      "partners": ["amex"]
    }
  }'
// Response
{
  "id": "subscription-uuid-123",
  "name": "openai-chatgpt-staging",
  "consumer_id": "openai-chatgpt-staging",
  "filters": {
    "categories": ["*"],
    "fact_event_types": ["offer", "product", "announcement"],
    "partners": ["amex"]
  },
  "position": {
    "cursor": null,
    "lastEventId": null,
    "lastUpdated": "2025-07-10T00:00:00Z"
  },
  "status": "active",
  "createdAt": "2025-07-10T00:00:00Z"
}

Pull-based Consumption via Cursor

Great for testing, but not recommended for production use.

curl -H "Authorization: Bearer your-jwt-token" \
  "https://api.entersignal.com/v1/subscriptions/subscription-uuid-123/data?limit=20&cursor=eyJsYXN0X2lkIjoiMTIzIn0"
// Response
{
  "data": [
    {
      "event": {
         "id": "evt_01HRB9QF1WQ8KJD4X7TZ9VG1K2",
         // A fact event
         // .....
      }
      "cursor": "eyJsYXN0X2lkIjoiMTI0In0",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "cursor": "eyJsYXN0X2lkIjoiMTI0In0",
    "has_more": true,
    "total_count": 150
  },
  "metadata": {
    "subscription_id": "subscription-uuid-123",
    "timestamp": "2025-07-10T00:00:00Z",
    "last_updated": "2025-07-10T00:00:00Z"
  }
}
```

Push-based Consumption via Webhooks 

curl -X POST /subscriptions/uuid-123/webhooks \
  -d '{
    "url": "https://your-ai-system.com/webhook",
    "secret": "your-webhook-secret",
    "startPosition": {
      "type": "event_time",
      "value": "2025-07-10T00:00:00Z"
    },
    // By default, if an older timestamp is specified, do not backfill.
    // You can also use the archive to backfill (see below).
    "backfill": {
      "enabled": true,
      "maxEvents": 100,
      "batchSize": 10,
      "delayBetweenBatches": 2,
      "backfill_url_override": "https://your-ai-system.com/webhook_backfill"
    }
  }'

Offline Consumption

We maintain an offline archive for every subscription created. You can access it by querying the /v1/subscriptions/[subscription_id]/archive endpoint to obtain the presigned URI.

curl https://api.entersignal.com/v1/subscriptions/subscription-uuid-123/archive \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-jwt-token"
// Response
{
  "id": "subscription-uuid-123",
  // ...
  "presigned_uri": "s3://entersignal_archive/subscriptions/subscription-uuid-123",
  // ....
  "status": "active",
  "createdAt": "2025-07-10T00:00:00Z"
}

© 2025 Enter Signal