--- title: "Create a broadcast event" method: POST path: "/v1/projects/{projectID}/events/broadcast" tags: ["Events"] --- # Create a broadcast event `POST /v1/projects/{projectID}/events/broadcast` This endpoint creates a event that is broadcast to every endpoint whose subscription matches the given event type. ## Path parameters - `projectID` string, required ## Request body - ModelsBroadcastEvent - `acknowledged_at` string - `custom_headers` object, nullable — Specifies custom headers you want convoy to add when the event is dispatched to your endpoint - `data` object, nullable — Data is an arbitrary JSON value that gets sent as the body of the webhook to the endpoints - `event_type` string — Event Type is used for filtering and debugging e.g invoice.paid - `idempotency_key` string — Specify a key for event deduplication ## Response `201` Created - object - `message` string - `status` boolean - `data` ModelsEventResponse - `acknowledged_at` string, nullable - `app_id` string — Deprecated - `created_at` string - `data` object, nullable — Data is an arbitrary JSON value that gets sent as the body of the webhook to the endpoints - `deleted_at` string, nullable - `endpoint_metadata` DatastoreEndpoint[] - `advanced_signatures` boolean - `authentication` DatastoreEndpointAuthentication - `api_key` DatastoreApiKey - `header_name` string - `header_value` string - `basic_auth` DatastoreBasicAuth - `password` string - `username` string - `oauth2` DatastoreOAuth2 - `audience` string - `authentication_type` 'shared_secret' | 'client_assertion' | '' - `client_id` string - `client_secret` string — Encrypted at rest - `expiry_time_unit` 'seconds' | 'milliseconds' | 'minutes' | 'hours' | '' - `field_mapping` DatastoreOAuth2FieldMapping - `access_token` string — Field name for access token (e.g., "accessToken", "access_token", "token") - `expires_in` string — Field name for expiry time (e.g., "expiresIn", "expires_in", "expiresAt") - `token_type` string — Field name for token type (e.g., "tokenType", "token_type") - `grant_type` string - `issuer` string - `scope` string - `signing_algorithm` string - `signing_key` DatastoreOAuth2SigningKey - `crv` string — EC (Elliptic Curve) key fields - `d` string — Private key (EC only) - `dp` string — RSA first factor CRT exponent (RSA private key only) - `dq` string — RSA second factor CRT exponent (RSA private key only) - `e` string — RSA public exponent (RSA only) - `kid` string — Key ID - `kty` string — Key type: "EC" or "RSA" - `n` string — RSA key fields - `p` string — RSA first prime factor (RSA private key only) - `q` string — RSA second prime factor (RSA private key only) - `qi` string — RSA first CRT coefficient (RSA private key only) - `x` string — X coordinate (EC only) - `y` string — Y coordinate (EC only) - `subject` string - `url` string - `type` 'api_key' | 'oauth2' | 'basic_auth' | '' - `cb_state` string, nullable — CBState is the circuit breaker state ("open", "half-open", "closed") so the UI can reflect a tripped breaker on the endpoint status. Nil when CB is off/unlicensed or has no sample for this endpoint. - `content_type` string - `created_at` string - `deleted_at` string, nullable - `description` string - `events` integer - `failure_count` integer, nullable - `failure_rate` number, nullable — FailureRate is the circuit breaker's rolling failure rate for this endpoint. It is a pointer so the API can return null when no rate was computed (circuit breaker feature off, or sampler not running), distinct from a genuine 0%. - `http_timeout` integer - `mtls_client_cert` DatastoreMtlsClientCert - `client_cert` string — ClientCert is the client certificate PEM string - `client_key` string — ClientKey is the client private key PEM string - `name` string - `owner_id` string - `period_failure_rate` number, nullable — PeriodFailureRate is the period failure rate from event_deliveries, (Failure+Retry)/(Success+Failure+Retry). Retry counts as failed-so-far. Nil when the range has no counted deliveries; sibling counts are transient. - `project_id` string - `rate_limit` integer - `rate_limit_duration` integer - `retry_count` integer, nullable - `secrets` DatastoreSecret[] - `created_at` string - `deleted_at` string, nullable - `expires_at` string, nullable - `uid` string - `updated_at` string - `value` string - `slack_webhook_url` string - `status` 'active' | 'inactive' | 'paused' | '' - `success_count` integer, nullable - `support_email` string - `uid` string - `updated_at` string - `url` string - `endpoints` string[] - `event_type` string - `failure_reason` string — FailureReason explains a Failure status to whoever is looking at the dashboard. It carries operator facing text only, never endpoint credentials, headers, or payload content. - `headers` HttpheaderHTTPHeader, nullable - `idempotency_key` string - `is_duplicate_event` boolean - `project_id` string - `raw` string - `source_id` string - `source_metadata` DatastoreSource - `body_function` string, nullable - `created_at` string - `custom_response` DatastoreCustomResponse - `body` string - `content_type` string - `deleted_at` string, nullable - `event_type_location` string - `forward_headers` string[] - `header_function` string, nullable - `idempotency_keys` string[] - `is_disabled` boolean - `mask_id` string - `name` string - `project_id` string - `provider` 'github' | 'twitter' | 'shopify' | '' - `provider_config` DatastoreProviderConfig - `twitter` DatastoreTwitterProviderConfig - `crc_verified_at` string, nullable - `pub_sub` DatastorePubSubConfig - `amqp` DatastoreAmqpPubSubConfig - `host` string - `auth` DatastoreAmqpCredentials - `password` string - `user` string - `bindedExchange` string, nullable - `deadLetterExchange` string, nullable - `port` string - `queue` string - `routingKey` string - `schema` string - `vhost` string, nullable - `google` DatastoreGooglePubSubConfig - `project_id` string - `service_account` string, byte — encoding/json marshals []byte as a base64 string on the wire. - `subscription_id` string - `kafka` DatastoreKafkaPubSubConfig - `auth` DatastoreKafkaAuth - `hash` string - `password` string - `tls` boolean - `type` string - `username` string - `brokers` string[] - `consumer_group_id` string - `topic_name` string - `sqs` DatastoreSQSPubSubConfig - `access_key_id` string - `default_region` string - `endpoint` string — Optional: for LocalStack testing - `queue_name` string - `secret_key` string - `type` 'sqs' | 'google' | 'kafka' | 'amqp' | '' - `workers` integer - `type` 'http' | 'rest_api' | 'pub_sub' | 'db_change_stream' | '' - `uid` string - `updated_at` string - `url` string - `verifier` DatastoreVerifierConfig - `api_key` DatastoreApiKey - `header_name` string - `header_value` string - `basic_auth` DatastoreBasicAuth - `password` string - `username` string - `hmac` DatastoreHMac - `encoding` 'base64' | 'hex' | '' - `hash` string - `header` string - `secret` string - `type` 'noop' | 'hmac' | 'basic_auth' | 'api_key' | '' - `status` 'Processing' | 'Failure' | 'Success' | 'Retry' | 'Pending' | '' - `uid` string - `updated_at` string - `url_path` string - `url_query_params` string ## Other responses - `400` — Bad Request - `401` — Unauthorized - `404` — Not Found --- [API](https://skmtc.net/getconvoy/apis/convoy-api-reference.md) · [All operations](https://skmtc.net/getconvoy/apis/convoy-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getconvoy/convoy-api-reference/versions/9d68b6f4aead/schema)