Sign in
Start free7-day free trial
Live API contract
API REFERENCE / Webhooks

Create a webhook endpoint

POST/v1/webhooks

Creates a webhook endpoint and returns its signing secret. the only time the secret is ever shown in full. At most 10 active endpoints are allowed per organization.

Authentication

Send an organization-scoped API key in the Authorization header. Keep credentials on your server.

webhooks:manage
Authentication and API keys →

Request body

Use application/json. Replace example identifiers and values with data from your organization.

urlstringrequired

Length: 1 to 1000 characters.

eventsarrayrequired

Responses

201 Response schema

application/json

endpointobjectrequired
View nested fields
idstring · uuidrequired
urlstringrequired
eventsarrayrequired
activebooleanrequired
createdAtstring · date-timerequired
lastDeliveryobject | nullrequired
secretstringrequired
View complete response schema
HTTP 201 schema
{
  "type": "object",
  "properties": {
    "endpoint": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
        },
        "url": {
          "type": "string"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "waiver.signed",
              "waiver.voided",
              "waiver.expired",
              "checkin.created",
              "waiver.flagged",
              "invitee.bounced",
              "import.completed",
              "ping"
            ]
          }
        },
        "active": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "lastDelivery": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "queued",
                    "running",
                    "completed",
                    "failed"
                  ]
                },
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "responseCode": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "status",
                "at",
                "responseCode"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "url",
        "events",
        "active",
        "createdAt",
        "lastDelivery"
      ],
      "additionalProperties": false
    },
    "secret": {
      "type": "string"
    }
  },
  "required": [
    "endpoint",
    "secret"
  ],
  "additionalProperties": false
}

401 Response schema

application/json

errorobjectrequired
View nested fields
codestringrequired
messagestringrequired
requestIdstringrequired
detailsvalue
View complete response schema
HTTP 401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "details": {}
      },
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

403 Response schema

application/json

errorobjectrequired
View nested fields
codestringrequired
messagestringrequired
requestIdstringrequired
detailsvalue
View complete response schema
HTTP 403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "details": {}
      },
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

404 Response schema

application/json

errorobjectrequired
View nested fields
codestringrequired
messagestringrequired
requestIdstringrequired
detailsvalue
View complete response schema
HTTP 404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "details": {}
      },
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

409 Response schema

application/json

errorobjectrequired
View nested fields
codestringrequired
messagestringrequired
requestIdstringrequired
detailsvalue
View complete response schema
HTTP 409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "details": {}
      },
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

422 Response schema

application/json

errorobjectrequired
View nested fields
codestringrequired
messagestringrequired
requestIdstringrequired
detailsvalue
View complete response schema
HTTP 422 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "details": {}
      },
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

429 Response schema

application/json

errorobjectrequired
View nested fields
codestringrequired
messagestringrequired
requestIdstringrequired
detailsvalue
View complete response schema
HTTP 429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "details": {}
      },
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Authentication and validation failures use the shared error envelope. Save the request ID when diagnosing a failed call.

Build the surrounding workflow

Read the webhooks guide for ordering, verification and recovery. Browse the other webhooks endpoints when you need the next operation.