Create Amazon SNS integration

Returns either a newly created Amazon SNS integration, or validation errors. Subscribe a topic to the returned url to start receiving notifications, as described in the Amazon SNS integration guide. Leave Enable raw message delivery off on that subscription, or every notification is rejected with 400.

POST https://uptime.betterstack.com/api/v2/amazon-sns

Headers

Authorization

required string

Bearer $TOKEN

Content-Type

string

application/json

Body parameters

team_name

string

Required if using global API token to specify the team which should own the resource

name

string

The name of the Amazon SNS integration that you can see in the dashboard.

Any other params you'd like to set. See the list of all Amazon SNS integration API parameters for details.

201

Returns newly created Amazon SNS integration

Response body

{
  "data": {
    "id": "5",
    "type": "amazon_sns_integration",
    "attributes": {
      "name": "Backend alerts",
      "created_at": "2026-09-09T10:06:12.418Z",
      "updated_at": "2026-09-09T10:06:12.418Z",
      "policy_id": null,
      "url": "https://uptime.betterstack.com/api/v1/incoming-webhook/[token]",
      "sample_query_string": null,
      "sample_headers": null,
      "sample_body": null,
      "team_name": "Testing",
      "call": false,
      "sms": false,
      "email": true,
      "push": true,
      "critical_alert": false,
      "team_wait": 180,
      "recovery_period": 0,
      "paused": false,
      "started_rule_type": "unused",
      "acknowledged_rule_type": "unused",
      "resolved_rule_type": "unused",
      "started_rules": [],
      "acknowledged_rules": [],
      "resolved_rules": [],
      "cause_field": {
        "name": null,
        "special_type": "cause",
        "field_target": "body",
        "match_type": "match_everything",
        "target_field": null,
        "content": null,
        "content_before": null,
        "content_after": null
      },
      "title_field": {
        "name": null,
        "special_type": "title",
        "field_target": "sns_envelope",
        "match_type": "match_everything",
        "target_field": "Subject",
        "content": null,
        "content_before": null,
        "content_after": null
      },
      "started_alert_id_field": {
        "name": null,
        "special_type": "alert_id",
        "field_target": "body",
        "match_type": "match_everything",
        "target_field": null,
        "content": null,
        "content_before": null,
        "content_after": null
      },
      "acknowledged_alert_id_field": null,
      "resolved_alert_id_field": null,
      "other_started_fields": null,
      "other_acknowledged_fields": null,
      "other_resolved_fields": null,
      "topic_arn": null,
      "subscription_state": "awaiting"
    }
  }
}

Example cURL

Example

Copied!

curl -X "POST" "https://uptime.betterstack.com/api/v2/amazon-sns/" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Backend alerts"
}'

What does a new integration extract by default?

The incident title comes from the notification's Subject, and the cause and alert ID from the message, so a test publish raises a useful incident straight away. Send cause_field, title_field, or started_alert_id_field to replace them, or title_field: null to drop the title extraction.

Why can't I set `topic_arn`?

Better Stack writes topic_arn and subscription_state itself once AWS confirms the subscription, so both are read-only. Sending either one returns 422, as does any other attribute the endpoint does not recognize.

Looking for the details of a specific parameter?

Explore the list of all Amazon SNS integration API parameters.

Get Amazon SNS integration

Update Amazon SNS integration

Explore documentation

Create Amazon SNS integration

Example cURL

What does a new integration extract by default?

Why can't I set topic_arn?

Looking for the details of a specific parameter?

Please accept cookies

Why can't I set `topic_arn`?