# 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](/d/api-docs/authentication/user-action-signing.md) for more information.
* Request headers required. See [Request Headers](/d/advanced-topics/authentication/request-headers.md) for more information.
* Authentication required. See [Authentication Headers](/d/advanced-topics/authentication/request-headers.md#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="/pages/rYjtWyHs7nivyQhPbpVj#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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-legacy.dfns.co/d/api-docs/webhooks/create-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.