Workspace: webhooks

The workspace’s webhook endpoints. Never their signing secrets

GET /v1/workspace/webhooks · operation listWebhooks

Requires the batondeck:workspace:admin permission (action webhook:read).

Responses

Status	Meaning
200	The workspace’s webhook endpoints. Never their signing secrets
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "consecutive_failures": {
            "type": "number"
          },
          "rotating_until": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "number"
          },
          "updated_at": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "status",
          "consecutive_failures",
          "rotating_until",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "endpoints",
    "events",
    "enabled"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/workspace/webhooks' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Register an endpoint. The signing secret is in this answer and nowhere else

POST /v1/workspace/webhooks · operation createWebhook

Requires the batondeck:workspace:admin permission (action webhook:create).

Requires a step-up: MFA enrolled and re-authenticated within 15 minutes. Not reachable with an API key — a key has no session and so can never step up.

Refused while the workspace is suspended or on deletion hold.

Request body (application/json)

Field	Type	Required	Notes
url	string	yes	≥ 1 chars
events	array of string	yes	default []

Request schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "minLength": 1
    },
    "events": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "url",
    "events"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
201	Register an endpoint. The signing secret is in this answer and nowhere else
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

201 response schema

{
  "type": "object",
  "properties": {
    "endpoint": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string"
        },
        "consecutive_failures": {
          "type": "number"
        },
        "rotating_until": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "number"
        },
        "updated_at": {
          "type": "number"
        }
      },
      "required": [
        "id",
        "url",
        "events",
        "status",
        "consecutive_failures",
        "rotating_until",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    },
    "secret": {
      "type": "string"
    }
  },
  "required": [
    "endpoint",
    "secret"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/workspace/webhooks' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

A new signing secret; the old one keeps working for 24 hours

POST /v1/workspace/webhooks/{id}/secret · operation rotateWebhookSecret

Requires the batondeck:workspace:admin permission (action webhook:manage).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
id	path	string	yes

Responses

Status	Meaning
200	A new signing secret; the old one keeps working for 24 hours
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "secret": {
      "type": "string"
    },
    "previous_accepted_until": {
      "type": "number"
    }
  },
  "required": [
    "secret",
    "previous_accepted_until"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/workspace/webhooks/:id/secret' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Pause an endpoint, or resume one — resuming clears its failure run

PATCH /v1/workspace/webhooks/{id} · operation setWebhookStatus

Requires the batondeck:workspace:admin permission (action webhook:manage).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
id	path	string	yes

Request body (application/json)

Field	Type	Required	Notes
status	“active” \	“paused”	yes

Request schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
200	Pause an endpoint, or resume one — resuming clears its failure run
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "consecutive_failures": {
            "type": "number"
          },
          "rotating_until": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "number"
          },
          "updated_at": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "status",
          "consecutive_failures",
          "rotating_until",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "endpoints"
  ],
  "additionalProperties": false
}

curl -X PATCH 'https://api.batondeck.com/v1/workspace/webhooks/:id' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Remove an endpoint. Its delivery log stays, so what it did is still readable

DELETE /v1/workspace/webhooks/{id} · operation deleteWebhook

Requires the batondeck:workspace:admin permission (action webhook:delete).

Allowed while the workspace is paused, suspended or on deletion hold: it only takes access away.

Parameters

Name	In	Type	Required	Notes
id	path	string	yes

Responses

Status	Meaning
204	Done. No body.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

curl -X DELETE 'https://api.batondeck.com/v1/workspace/webhooks/:id' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

What was attempted, when, and what came back

GET /v1/workspace/webhooks/{id}/deliveries · operation listWebhookDeliveries

Requires the batondeck:workspace:admin permission (action webhook:read).

Parameters

Name	In	Type	Required	Notes
id	path	string	yes
limit	query	integer	yes

Responses

Status	Meaning
200	What was attempted, when, and what came back
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "deliveries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "endpoint_id": {
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "attempt": {
            "type": "number"
          },
          "status": {
            "type": "string"
          },
          "http_status": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "latency_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "response_excerpt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "next_attempt_at": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "endpoint_id",
          "event_id",
          "event_type",
          "attempt",
          "status",
          "http_status",
          "latency_ms",
          "response_excerpt",
          "next_attempt_at",
          "created_at"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "deliveries"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/workspace/webhooks/:id/deliveries' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"