# Create Webhook

**`POST /webhooks`**

Registers a new webhook.  By default, organizations are limited to creating 5 webhooks.

{% hint style="info" %}

* User action signature required. See [User Action Signing](https://docs-legacy.dfns.co/d/api-docs/authentication/user-action-signing) for more information.
* Request headers required. See [Request Headers](https://docs-legacy.dfns.co/d/advanced-topics/authentication/request-headers) for more information.
* Authentication required. See [Authentication Headers](https://docs-legacy.dfns.co/d/advanced-topics/authentication/request-headers#authentication-headers) for more information.
  {% endhint %}

### Permissions Required

* `Webhooks:Create`

### Request Body

```json
{
  "url": "https://example.com/my/webhook/endpoint",
  "description": "My awesome webhook, it's so great", // optional
  "status": "Enabled" // optional
  "events": [                             
    "wallet.transfer.initiated",
    "wallet.transfer.executed",
    "wallet.transfer.confirmed",
  ],

}
```

<table data-full-width="true"><thead><tr><th width="132.33333333333331">Property</th><th width="193">Type - Optional</th><th>Description</th></tr></thead><tbody><tr><td>url</td><td>String - Required</td><td>The webhook endpoint url where events will be pushed. The url needs to be a valid http / https url.</td></tr><tr><td>description</td><td>String - Optional</td><td>Description of what the endpoint is for.</td></tr><tr><td>status</td><td>String - Optional</td><td>Possible values: <code>Enabled</code> | <code>Disabled</code>. If webhook status is <code>Disabled</code>, no event will be pushed to the webhook endpoint. If <code>status</code> is not specified, default status is <code>Enabled</code>.</td></tr><tr><td>events</td><td>String List - Required</td><td>List of <a href="..#supported-webhook-events">supported events</a> the webhook subscribes to (see full list here). You can also subscribe to all events by passing  <code>events: ["*"]</code>.</td></tr></tbody></table>

## Response

```json
{
  "id": "wh-xxx-xxxxxxx",
  "url": "https://example.com/my/webhook/endpoint",
  "events": [
    "wallet.transfer.initiated",
    "wallet.transfer.executed",
    "wallet.transfer.confirmed",
  ],
  "description": "My awesome webhook, it's so great",
  "status": "Enabled",
  "dateCreated": "2023-11-01T08:52:01.186Z",
  "dateUpdated": "2023-11-01T08:52:01.186Z",
  "secret": "whs-Fij3kMCRZLCAzOqnpLzVQUEKe9Rw5V8s" // only included once in the creation endpoint
}
```

<table data-full-width="true"><thead><tr><th width="149.33333333333331">Property</th><th width="193">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>ID of the webhook</td></tr><tr><td>url</td><td>String</td><td>See above</td></tr><tr><td>description</td><td>String - Optional</td><td>See above</td></tr><tr><td>status</td><td>String</td><td>See above</td></tr><tr><td>events</td><td>String List</td><td>See above</td></tr><tr><td>dateCreated</td><td>String</td><td>ISO 8601 string representing date of creation of the webhook</td></tr><tr><td>dateUpdated</td><td>String</td><td>ISO 8601 string representing date of update of the webhook</td></tr><tr><td>secret</td><td>String</td><td>Secret which can be used to verify authenticity of the message received by the webhook (more details here). The <code>secret</code> is only included in the "Create Webhook" response, we will never show it to you again, so you need to save it securely on your side upon webhook creation.</td></tr></tbody></table>