---
updatedAt: 2026-09-11T18:34:39.000Z
---

# Create Webhook

Create a webhook to use for callbacks from Pinwheel jobs.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "contact": {
      "email": "support@getpinwheel.com",
      "name": "Support",
      "url": "https://getpinwheel.com"
    },
    "description": "Pinwheel is the API for direct deposit switching, bill switching, and income & employment verification.",
    "title": "Pinwheel",
    "version": "v2025-07-08"
  },
  "servers": [
    {
      "description": "production",
      "url": "https://api.getpinwheel.com/v1"
    },
    {
      "description": "sandbox",
      "url": "https://sandbox.getpinwheel.com/v1"
    },
    {
      "description": "development",
      "url": "https://development.getpinwheel.com/v1"
    }
  ],
  "paths": {
    "/webhooks": {
      "post": {
        "description": "Create a webhook to use for callbacks from Pinwheel jobs.",
        "operationId": "post_v1_webhooks___post",
        "parameters": [
          {
            "description": "Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.",
            "in": "header",
            "name": "Pinwheel-Version",
            "required": true,
            "schema": {
              "default": "2025-07-08",
              "enum": [
                "2022-03-02",
                "2022-06-22",
                "2022-09-09",
                "2023-04-18",
                "2023-07-18",
                "2023-11-22",
                "2025-07-08"
              ],
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "example": {
                  "value": {
                    "enabled_events": [
                      "income.added",
                      "employment.added"
                    ],
                    "status": "active",
                    "url": "https://example.com/webhook_endpoint",
                    "version": "2023-04-18"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/WebhookCreate_v2023_04_18"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "value": {
                      "data": {
                        "created_at": "2020-11-06T15:59:13.530178+00:00",
                        "enabled_events": [
                          "income.added",
                          "employment.added"
                        ],
                        "id": "ae0047bf-cd48-4f41-9fa2-2e578ca82969",
                        "last_updated": "2020-11-06T16:00:00.530178+00:00",
                        "status": "active",
                        "url": "https://example.com/webhook_endpoint",
                        "version": "2023-04-18"
                      }
                    }
                  }
                },
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookObjResponse"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object",
                  "x-tags": [
                    "Schemas"
                  ]
                }
              }
            },
            "description": "OK"
          }
        },
        "summary": "Create Webhook",
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "WebhookCreate_v2023_04_18": {
        "properties": {
          "customer_id": {
            "description": "Banking platforms webhooks only: the customer ID associated with the platform's customer.",
            "title": "customer_id",
            "type": "string"
          },
          "enabled_events": {
            "description": "The list of events enabled for this webhook.",
            "items": {
              "enum": [
                "account.added",
                "account.additional_connections_recommended",
                "account.monitoring_status.updated",
                "bill_switch.added",
                "bill_switch.cancelled",
                "company_connect.census.added",
                "company_connect.employments.added",
                "company_connect.incomes.added",
                "company_connect.status.updated",
                "direct_deposit_allocations.added",
                "direct_deposit_switch.added",
                "documents.added",
                "earnings_stream.payouts.refreshed",
                "employment.added",
                "identity.added",
                "income.added",
                "paycheck_viewer.added",
                "paystubs.added",
                "paystubs.documents.added",
                "paystubs.fully_synced",
                "paystubs.ninety_days_synced",
                "paystubs.seven_days_synced",
                "paystubs.thirty_days_synced",
                "shifts.added",
                "shifts.fully_synced",
                "shifts.ninety_days_synced",
                "shifts.seven_days_synced",
                "shifts.thirty_days_synced",
                "tax_forms.added",
                "verification_reports.refreshed"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "status": {
            "allOf": [
              {
                "enum": [
                  "active",
                  "paused"
                ],
                "type": "string"
              }
            ],
            "description": "The status of the webhook."
          },
          "url": {
            "description": "The URL of the webhook endpoints. Must be 'https://'.",
            "title": "url",
            "type": "string"
          },
          "version": {
            "allOf": [
              {
                "enum": [
                  "2022-09-09",
                  "2023-04-18",
                  "2023-07-18",
                  "2023-11-22",
                  "2025-07-08"
                ],
                "type": "string"
              }
            ],
            "description": "The webhook's version, which determines the format of the webhook event payloads."
          }
        },
        "required": [
          "enabled_events",
          "status",
          "url",
          "version"
        ],
        "title": "WebhookPostBody",
        "type": "object",
        "x-tags": [
          "Schemas"
        ]
      },
      "WebhookObjResponse": {
        "properties": {
          "created_at": {
            "description": "ISO 8601 timestamp of created time.",
            "format": "date-time",
            "title": "created_at",
            "type": "string"
          },
          "customer_id": {
            "description": "Banking platforms webhooks only: the customer ID associated with the platform's customer.",
            "title": "customer_id",
            "type": "string"
          },
          "enabled_events": {
            "description": "The list of events enabled for this webhook.",
            "items": {
              "enum": [
                "account.added",
                "account.additional_connections_recommended",
                "account.monitoring_status.updated",
                "bill_switch.added",
                "bill_switch.cancelled",
                "company_connect.census.added",
                "company_connect.employments.added",
                "company_connect.incomes.added",
                "company_connect.status.updated",
                "direct_deposit_allocations.added",
                "direct_deposit_switch.added",
                "documents.added",
                "earnings_stream.payouts.refreshed",
                "employment.added",
                "identity.added",
                "income.added",
                "paycheck_viewer.added",
                "paystubs.added",
                "paystubs.documents.added",
                "paystubs.fully_synced",
                "paystubs.ninety_days_synced",
                "paystubs.seven_days_synced",
                "paystubs.thirty_days_synced",
                "shifts.added",
                "shifts.fully_synced",
                "shifts.ninety_days_synced",
                "shifts.seven_days_synced",
                "shifts.thirty_days_synced",
                "tax_forms.added",
                "verification_reports.refreshed"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "id": {
            "description": "Unique identifier for the object.",
            "format": "uuid",
            "title": "id",
            "type": "string"
          },
          "last_updated": {
            "description": "ISO 8601 timestamp of the last update to this object.",
            "format": "date-time",
            "title": "last_updated",
            "type": "string"
          },
          "status": {
            "allOf": [
              {
                "enum": [
                  "active",
                  "paused"
                ],
                "type": "string"
              }
            ],
            "description": "The status of the webhook."
          },
          "url": {
            "description": "The URL of the webhook endpoints.",
            "title": "url",
            "type": "string"
          },
          "version": {
            "allOf": [
              {
                "enum": [
                  "2022-09-09",
                  "2023-04-18",
                  "2023-07-18",
                  "2023-11-22",
                  "2025-07-08"
                ],
                "type": "string"
              }
            ],
            "description": "The webhook's version, which determines the format of the webhook event payloads."
          }
        },
        "required": [
          "created_at",
          "enabled_events",
          "id",
          "last_updated",
          "status",
          "url",
          "version"
        ],
        "title": "Webhook",
        "type": "object",
        "x-tags": [
          "Schemas"
        ]
      }
    },
    "securitySchemes": {
      "apiSecret": {
        "description": "API Secret",
        "in": "header",
        "name": "X-API-SECRET",
        "type": "apiKey"
      }
    }
  },
  "tags": [
    {
      "name": "Webhooks"
    }
  ],
  "security": [
    {
      "apiSecret": []
    }
  ]
}
```