---
title: "Create webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create webhook

`POST /webhooks`

Create a new webhook with a given URL. The URL will receive webhook
events as JSON-encoded `POST` requests. The URL must respond with a HTTP
`200` status on success.

There is currently a limit of 10 webhooks at any given time. Once this
limit is reached, existing webhooks will need to be deleted before new
webhooks can be created.

Event delivery is retried with exponential backoff if the URL is
unreachable or it does not respond with a `200` status. The response
includes a `secretKey` attribute, which is used to sign requests sent to
the webhook URL. It will not be returned from any other endpoints within
the Up API. If the `secretKey` is lost, simply create a new webhook with
the same URL, capture its `secretKey` and then delete the original
webhook. See [Handling webhook events](#callback_post_webhookURL) for
details on how to process webhook events.

It is probably a good idea to test the webhook by
[sending it a `PING` event](#post_webhooks_webhookId_ping) after creating
it.

## Request body

- CreateWebhookRequest — Request to create a new webhook. This currently only requires a `url` attribute.
  - `data` WebhookInputResource, required — Represents a webhook specified as request input.
    - `attributes` object, required
      - `url` string, uri, required — The URL that this webhook should post events to. This must be a valid HTTP or HTTPS URL that does not exceed 300 characters in length.
      - `description` string, nullable — An optional description for this webhook, up to 64 characters in length.

## Response `201`

Created

- CreateWebhookResponse — Successful response after creating a webhook.
  - `data` WebhookResource, required — Provides information about a webhook.
    - `type` string, required — The type of this resource: `webhooks`
    - `id` string, required — The unique identifier for this webhook.
    - `attributes` object, required
      - `url` string, required — The URL that this webhook is configured to `POST` events to.
      - `description` string, nullable, required — An optional description that was provided at the time the webhook was created.
      - `secretKey` string — A shared secret key used to sign all webhook events sent to the configured webhook URL. This field is returned only once, upon the initial creation of the webhook. If lost, create a new webhook and delete this webhook. The webhook URL receives a request with a `X-Up-Authenticity-Signature` header, which is the SHA-256 HMAC of the entire raw request body signed using this `secretKey`. It is advised to compute and check this signature to verify the authenticity of requests sent to the webhook URL. See [Handling webhook events](#callback_post_webhookURL) for full details.
      - `createdAt` string, date-time, required — The date-time at which this webhook was created.
    - `relationships` object, required
      - `logs` object, required
        - `links` object
          - `related` string, required — The link to retrieve the related resource(s) in this relationship.
    - `links` object
      - `self` string, required — The canonical link to this resource within the API.

## Changes

- **2020-07-29** (v1) `48ca1ca58cdd` — 2 info
  - added the new optional request property `data/allOf[#/components/schemas/WebhookInputResource]/attributes/description`
  - added the required property `data/allOf[#/components/schemas/WebhookResource]/attributes/description` to the response with the `201` status
- **2020-07-26** (v1) `503c1dbaec36` — 1 info
  - added the optional property `data/allOf[#/components/schemas/WebhookResource]/attributes/secretKey` to the response with the `201` status
- **2020-07-21** (v1) `2ac77a5de971` — 1 breaking, 2 warning
  - removed the required property `data/allOf[#/components/schemas/WebhookResource]/attributes/description` from the response with the `201` status
  - removed the request property `data/allOf[#/components/schemas/WebhookInputResource]/attributes/description`
  - removed the optional property `data/allOf[#/components/schemas/WebhookResource]/attributes/secretKey` from the response with the `201` status

[Change history](https://skmtc.dev/up-banking/apis/up-api/changes/webhooks/post.md)

---

[API](https://skmtc.dev/up-banking/apis/up-api.md) · [All operations](https://skmtc.dev/up-banking/apis/up-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/up-banking/up-api/revisions/cc6a5e6d809d/schema)