---
title: "Subscribe Event Webhook"
method: POST
path: "/v2/syncs/{sync_id}/webhooks"
tags: ["sync"]
---

# Subscribe Event Webhook

`POST /v2/syncs/{sync_id}/webhooks`

Enroll a connector for real-time change events. For AWS S3, pass your SNS topic's ARN: Captain binds it to this sync and returns the queue_arn of Captain's SQS queue to subscribe the topic to, so events flow AWS-natively with no HTTP endpoint or signature handling on your side. For GCS, R2, Supabase, and Backblaze, send an empty body: Captain mints a webhook secret and returns a private ingest_url to point the store's change notifications at, plus provider-specific setup steps. Pass rotate_secret to revoke a leaked ingest_url and mint a fresh one. Events complement the scheduled reconcile, which remains the reliability backstop. Idempotent per connector.

## Path parameters

- `sync_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- S3SyncSubscribeRequestDocs — Optional body. AWS S3 requires sns_topic_arn; webhook providers (GCS/R2/Supabase/Backblaze) enroll with an empty body.
  - `sns_topic_arn` string, nullable — ARN of your SNS topic that S3 event notifications are published to. Bound to the connector so events from this topic resolve here. AWS S3 only.
  - `rotate_secret` boolean — Webhook providers (GCS/R2/Supabase/Backblaze) only: mint a FRESH webhook secret, revoking the current ingest_url. Use if the URL may have leaked. The response returns the new ingest_url; the old one stops working immediately. Re-point your provider's webhook at the new URL.

## Response `200`

Successful Response

- S3SyncSubscribeResponseDocs
  - `sync_id` string
  - `queue_arn` string, nullable — Captain's SQS queue ARN to subscribe your SNS topic to (AWS S3 real-time events). Subscribe your topic to this ARN; Captain consumes it directly (AWS-native, no HTTP endpoint). Null for webhook providers.
  - `topic_arn_bound` string, nullable — The SNS topic ARN bound to this connector (echoed back when provided). Null for webhook providers.
  - `ingest_url` string, nullable — Webhook-provider ingest URL (GCS push / R2 / Supabase / Backblaze): point the provider's change notifications at this URL. The URL embeds this connector's secret; keep it private. Null for AWS S3.
  - `secret_set` boolean
  - `instructions` string[] — Provider-native setup steps for wiring real-time change events (S3: SNS -> Captain's SQS queue; webhook providers: pointing notifications at the ingest_url).

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runcaptain/api-reference/revisions/fe4649e3f4aa/schema)