Content Management API > Webhook

Create a new webhook

Body parameters

type string Required

Must be exactly "webhook".

attributes.name string Required

Unique name for the webhook

Example:

"Item type creation/update"

attributes.url string Required

The URL to be called

Example:

"https://www.example.com/webhook"

attributes.headers object Required

Additional headers that will be sent

Example:

{ "X-Foo": "Bar" }

attributes.events Required

Type: Array<object>

entity_type enum Required

The subject of webhook triggering

Example:

"item"

item_type Optional

item Optional

upload Optional

build_trigger Optional

environment Optional

maintenance_mode Optional

sso_user Optional

cda_cache_tags Optional

event_types Required

Type: Array<string>

filters Optional

Type: Array<object>, null

entity_type enum Required

item_type Optional

item Optional

build_trigger Optional

environment Optional

environment_type Optional

entity_ids Required

Type: Array<string>

attributes.custom_payload string, null Required

A custom payload

Example:

'{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }'

attributes.http_basic_user string, null Required

HTTP Basic Authorization username

Example:

"user"

attributes.http_basic_password string, null Required

HTTP Basic Authorization password. It is null when the webhook has no basic auth, or when the credentials you are using cannot manage the webhooks of the project.

Example:

"password"

attributes.enabled boolean Optional

Whether the webhook is enabled and sending events or not

attributes.payload_api_version string Optional

Specifies which API version to use when serializing entities in the webhook payload

Example:

"3"

attributes.nested_items_in_payload boolean Optional

Whether the you want records present in the payload to show blocks expanded or not

attributes.auto_retry boolean Optional

If enabled, the system will attempt to retry the call several times when the webhook operation fails due to timeouts or errors.

Returns

Returns a resource object of type webhook.

Examples

1
POST https://site-api.datocms.com/webhooks HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "webhook",
10
    "attributes": {
11
      "name": "Item type creation/update",
12
      "url": "https://www.example.com/webhook",
13
      "headers": {
14
        "X-Foo": "Bar"
15
      },
16
      "events": [
17
        {
18
          "entity_type": "item",
19
          "event_types": [
20
            "update"
21
          ]
22
        }
23
      ],
24
      "custom_payload": "{ \"message\": \"{{event_type}} event triggered on {{entity_type}}!\", \"entity_id\": \"{{#entity}}{{id}}{{/entity}}\"] }",
25
      "http_basic_user": "user",
26
      "http_basic_password": "password"
27
    }
28
  }
29
}

1
curl -g 'https://site-api.datocms.com/webhooks' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"webhook","attributes":{"name":"Item type creation/update","url":"https://www.example.com/webhook","headers":{"X-Foo":"Bar"},"events":[{"entity_type":"item","event_types":["update"]}],"custom_payload":"{ \"message\": \"{{event_type}} event triggered on {{entity_type}}!\", \"entity_id\": \"{{#entity}}{{id}}{{/entity}}\"] }","http_basic_user":"user","http_basic_password":"password"}}}'

1
await fetch("https://site-api.datocms.com/webhooks", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "webhook",
12
      attributes: {
13
        name: "Item type creation/update",
14
        url: "https://www.example.com/webhook",
15
        headers: { "X-Foo": "Bar" },
16
        events: [{ entity_type: "item", event_types: ["update"] }],
17
        custom_payload:
18
          '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }',
19
        http_basic_user: "user",
20
        http_basic_password: "password",
21
      },
22
    },
23
  }),
24
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "webhook",
10
    "id": "312",
11
    "attributes": {
12
      "name": "Item type creation/update",
13
      "url": "https://www.example.com/webhook",
14
      "enabled": true,
15
      "headers": {
16
        "X-Foo": "Bar"
17
      },
18
      "events": [
19
        {
20
          "entity_type": "item",
21
          "event_types": [
22
            "update"
23
          ]
24
        }
25
      ],
26
      "http_basic_user": "user",
27
      "http_basic_password": "password",
28
      "custom_payload": "{ \"message\": \"{{event_type}} event triggered on {{entity_type}}!\", \"entity_id\": \"{{#entity}}{{id}}{{/entity}}\"] }",
29
      "payload_api_version": "3",
30
      "nested_items_in_payload": true,
31
      "auto_retry": true
32
    }
33
  }
34
}