# Add a webhook endpoint (/docs/reference/webhooks)

`POST https://api.getmattered.com/api/v1/developer/webhooks`

Adds a webhook endpoint to your account, at most 5. Answers the signing secret once. GetMattered POSTs a JSON event (`DeveloperWebhookEvent`) when one of your applications becomes `landed`, `not_landed`, `needs_you` or `held_for_review`, usually within two minutes. Each delivery carries `GetMattered-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the endpoint secret>`, plus `GetMattered-Event-Id` and `GetMattered-Event-Type`. Answer 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 5, 10 and 24 hours, then the delivery is marked `failed`. The same event can arrive twice: skip an `id` you have seen. Free.

Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md).

## Request body (application/json)

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "Where GetMattered POSTs events. Public `https` only; redirects are not followed.",
      "example": "https://example.com/hooks/getmattered"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## Responses

### 201: The endpoint and its signing secret, shown this once.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "createdAt": {
          "type": "string",
          "example": "2026-11-19 17:00:00"
        },
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "description": "The webhook endpoint.",
          "example": 7
        },
        "secretPrefix": {
          "type": "string",
          "description": "The first characters of the signing secret.",
          "example": "whsec_AbCdEf"
        },
        "url": {
          "type": "string",
          "example": "https://example.com/hooks/getmattered"
        },
        "secret": {
          "type": "string",
          "description": "The signing secret. Shown once: store it now. Verify each delivery with it (see `GetMattered-Signature`).",
          "example": "whsec_3q2-7wAbCdEfGhIjKlMnOpQrStUvWxYz0123456789"
        }
      },
      "required": [
        "createdAt",
        "id",
        "secretPrefix",
        "url",
        "secret"
      ],
      "additionalProperties": false
    },
    "meta": {
      "type": "object",
      "properties": {
        "duration": {
          "type": "number",
          "minimum": 0,
          "description": "Request duration in milliseconds",
          "example": 150
        },
        "performance": {
          "type": "object",
          "properties": {
            "dbQueries": {
              "type": "integer",
              "minimum": 0
            },
            "totalDbTime": {
              "type": "number",
              "minimum": 0
            }
          },
          "description": "Performance metrics (preview/local only)"
        },
        "requestId": {
          "type": "string",
          "description": "Unique request identifier",
          "example": "req_abc123"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp",
          "example": "2026-11-17T12:00:00.000Z"
        },
        "version": {
          "type": "string",
          "description": "API version",
          "example": "v1"
        }
      }
    },
    "success": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "required": [
    "data",
    "success"
  ],
  "additionalProperties": false,
  "description": "Successful API response"
}
```

### 400: Bad Request

### 401: Unauthorized

### 404: Not Found

### 409: Conflict

### 429: Too Many Requests

### 500: Internal Server Error

Error responses use the envelope in /errors.md.