# Create outgoing webhook 

Returns either a newly created Outgoing Webhook integration, or validation errors.

[endpoint]
base_url = "https://incidents.betterstack.com"
path = "/api/v2/outgoing-webhooks"
method = "POST"

[[body_param]]
name = "team_name"
description = "Required if using [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team which should own the resource."
required = false
type = "string"

[[body_param]]
name = "name"
description = "The name of the Outgoing Webhook integration that you can see in the dashboard."
required = false
type = "string"

[[body_param]]
name = "url"
description = "The URL of the Outgoing Webhook integration."
required = true
type = "string"

[[body_param]]
name = "trigger_type"
description = "The type of trigger for the Outgoing Webhook integration. Possible values are `on_call_change`, `incident_change` and `monitor_change`."
required = true
type = "string"

[[body_param]]
name = "metadata_api_version"
description = "Controls how the `$METADATA` variables in `url` and `body_template` render, as described in [metadata variables](https://betterstack.com/docs/uptime/webhooks/#metadata-variables). Possible values are `v3` and `v2`. New integrations default to `v3`. Only the metadata variables differ between the versions."
required = false
type = "string"

[[body_param]]
name = "notify_alongside_primary_responder"
description = "Whether to notify this integration alongside the primary responder when no escalation policy is configured. Only applicable if `trigger_type` is `incident_change`. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_started"
description = "Whether to trigger the Outgoing Webhook integration when an incident starts. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_acknowledged"
description = "Whether to trigger the Outgoing Webhook integration when an incident is acknowledged. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_resolved"
description = "Whether to trigger the Outgoing Webhook integration when an incident is resolved. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_reopened"
description = "Whether to trigger the Outgoing Webhook integration when an incident is reopened. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_comment"
description = '''Whether to trigger the Outgoing Webhook integration when a new comment is added to an incident. Only applicable if `trigger_type` is `incident_change`.

<br/><br/>

```json
[label Example `incident_change` payload when event is `comment`]
{
  "event": "comment",
  "data": {
    "id": "1",
    "type": "incident",
    "attributes": {
      "name": "Tesla.com homepage",
      "url": "https://tesla.com",
      "http_method": "get",
      "cause": "Error 500",
      "started_at": "2020-10-21T10:51:28.151Z",
      "acknowledged_at": "2020-02-25T17:38:45.768Z",
      "resolved_at": null,
      "response_content": null,
      "response_url": null,
      "screenshot_url": null
    },
    "relationships": {
      "monitor": {
        "data": { "id": "4", "type": "monitor" }
      }
    }
  },
  "comment": {
    "id": "42",
    "type": "incident_comment",
    "attributes": {
      "content": "Investigating — the database has been failing over.",
      "created_at": "2020-10-21T10:55:12.812Z",
      "updated_at": "2020-10-21T10:55:12.812Z",
      "user_id": 7,
      "user_email": "jane@example.com"
    }
  }
}
```
'''
required = false
type = "boolean"

[[body_param]]
name = "custom_webhook_template_attributes"
description = "Use this to specify the custom webhook template attributes. See below."
required = false
type = "object"

[[body_param]]
name = "custom_webhook_template_attributes.http_method"
description = "The HTTP method to use when sending the webhook. Possible values are `get`, `post`, `put`, `patch` and `head`."
required = false
type = "string"

[[body_param]]
name = "custom_webhook_template_attributes.auth_username"
description = "The username to use for basic authentication."
required = false
type = "string"

[[body_param]]
name = "custom_webhook_template_attributes.auth_password"
description = "The password to use for basic authentication."
required = false
type = "string"

[[body_param]]
name = "custom_webhook_template_attributes.headers_template"
description = '''
The headers to send with the webhook.
<br/><br/>

```json
[label Each header is an object with `name` and `value` keys.]
{
  "custom_webhook_template_attributes": {
    "headers_template": [
      { "name": "Content-Type", "value": "application/json" },
      { "name": "X-Custom-Header", "value": "Custom-Value" }
    ]
  }
}
```
'''
required = false
type = "array"

[[body_param]]
name = "custom_webhook_template_attributes.body_template"
description = '''
The body to send with the webhook. The value can be a stringified JSON or a JSON object.
<br/><br/>

```json
[label Using JSON object]
{
  "custom_webhook_template_attributes": {
    "body_template": {
      "data": {
        "id": "$INCIDENT_ID",
        "type": "incident",
        "attributes": {
          "name": "$NAME",
          "url": "$URL",
          "http_method": "$HTTP_METHOD",
          "screenshot_url": "$SCREENSHOT_URL"
        }
      }
    }
  }
}
```

```json
[label Using stringified JSON]
{
  "custom_webhook_template_attributes": {
    "body_template": "{\"data\":{\"id\":\"$INCIDENT_ID\",\"type\":\"incident\",\"attributes\":{\"name\":\"$NAME\",\"url\":\"$URL\",\"http_method\":\"$HTTP_METHOD\",\"screenshot_url\":\"$SCREENSHOT_URL\"}}}"
  }
}
```

When not specified, the default template is used. Each `trigger_type` has its own default template:
<br/><br/>


```json
[label Default template for `on_call_change`]
{
  "data":{
    "message": "$MESSAGE",
    "emails": $EMAILS_JSON_ARRAY,
    "on_holiday_emails": $ON_HOLIDAY_EMAILS_JSON_ARRAY,
    "change": "$CHANGE",
    "calendar_id": $ON_CALL_CALENDAR_ID,
    "calendar_name": "$ON_CALL_CALENDAR_NAME",
    "primary_calendar": $DEFAULT_ON_CALL_CALENDAR
  }
}
```

```json
[label Default template for `incident_change`]
{
  "data": {
    "id": "$INCIDENT_ID",
    "type": "incident",
    "attributes": {
      "name": "$NAME",
      "url": "$URL",
      "http_method": "$HTTP_METHOD",
      "cause": "$CAUSE",
      "started_at": "$STARTED_AT",
      "acknowledged_at": "$ACKNOWLEDGED_AT",
      "resolved_at": "$RESOLVED_AT",
      "response_content": "$RESPONSE_CONTENT",
      "response_url": "$RESPONSE_URL",
      "screenshot_url": "$SCREENSHOT_URL"
    }
  }
}
```

```json
[label Default template for `monitor_change`]
{
  "data":{
    "id": "$MONITOR_ID",
    "type": "monitor",
    "attributes":{
      "url": "$URL",
      "pronounceable_name": "$PRONOUNCEABLE_NAME",
      "monitor_type": "$MONITOR_TYPE",
      "required_keyword": "$REQUIRED_KEYWORD",
      "verify_ssl": $VERIFY_SSL,
      "check_frequency": $CHECK_FREQUENCY,
      "call": $CALL,
      "sms": $SMS,
      "email": $EMAIL,
      "team_wait": "$TEAM_WAIT",
      "http_method": "$HTTP_METHOD",
      "request_timeout": "$REQUEST_TIMEOUT",
      "recovery_period": "$RECOVERY_PERIOD",
      "request_body": "$REQUEST_BODY",
      "paused_at": "$PAUSED_AT",
      "last_checked_at": "$LAST_CHECKED_AT"
    }
  }
}
```

'''
required = false
type = "string|JSON"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = false
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''Returns the newly created Outgoing Webhook integration'''
body = '''{
  "data": {
    "id": "16",
    "type": "outgoing_webhook",
    "attributes": {
      "name": "test",
      "url": "https://example.com",
      "trigger_type": "on_call_change",
      "team_name": "My team"
    },
    "relationships": {
      "custom_webhook_template": {
        "data": null
      }
    }
  },
  "included": []
}'''

[/responses]

#### Example cURL

```shell
[label Example]
curl -X "POST" "https://incidents.betterstack.com/api/v2/outgoing-webhooks/" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Test",
  "url": "https://example.com",
  "trigger_type": "on_call_change"
}'
```

[info]
#### Looking for the details of a specific parameter?
Explore [the list of all Outgoing Webhook integration API parameters](https://betterstack.com/docs/uptime/api/outgoing-webhook-integrations-response-params/)
[/info]