> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Webhook Destination

> Update a webhook destination. **`subscribed_events` is REPLACED wholesale, not merged** — fetch first, append, resend. Secret is not rotated.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Update Webhook Destination API Prompt"
  prompt={`Update a Didit webhook destination through the Management API.

Endpoint:
PATCH https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
- Change a destination's label, url, enabled state, webhook_version, or subscribed_events. Send only the fields you want to change.

Path parameter:
- destination_uuid — the destination UUID from GET /v3/webhook/destinations/.

Request body (application/json) — all fields optional:
{
"label": "Updated label",
"url": "https://yourapp.com/webhooks/v2",
"enabled": false,
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated", "transaction.created"]
}

Critical semantics:
- subscribed_events is replaced wholesale, NOT merged. To add an event, GET the current destination, append to the list, and send the full array back. Sending [] returns 400.
- url must remain unique among the application's non-deleted destinations.
- webhook_version applies to future deliveries only. Already-queued deliveries use the version that was active when they were enqueued.
- The signing secret (secret_shared_key) is NOT rotated by PATCH. Console offers a manual rotation flow.

Example call (replace subscription list):
curl -X PATCH "https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/" \\
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \\
-d '{"subscribed_events": ["status.updated", "data.updated", "transaction.created"]}'

# Pause a destination without losing config:
curl -X PATCH "https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/" \\
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \\
-d '{"enabled": false}'

Failure modes:
- 400 — empty subscribed_events, unknown event name, duplicate url among destinations, or invalid webhook_version.
- 401 — missing or malformed x-api-key.
- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.
- 404 — destination not found in this application.

Side effects:
- Subsequent webhook deliveries respect the new url, enabled flag, and subscribed_events list.

For the full integration shape, see /integration/integration-prompt.`}
/>

Use this endpoint to change where a destination sends webhooks and which events it receives.

## Updating `subscribed_events`

When you send `subscribed_events`, provide the complete event list that should remain subscribed after the update. The array replaces the previous subscription set.

```json theme={null}
{
  "subscribed_events": [
    "status.updated",
    "data.updated",
    "transaction.created",
    "transaction.status.updated"
  ]
}
```

Supported values are:

| Event                        | What it represents                                                             |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `status.updated`             | User Verification (KYC) or Business Verification (KYB) session status changed. |
| `data.updated`               | Session verification data changed after creation.                              |
| `user.status.updated`        | User entity status changed.                                                    |
| `user.data.updated`          | User entity data changed.                                                      |
| `business.status.updated`    | Business entity status changed.                                                |
| `business.data.updated`      | Business entity data changed.                                                  |
| `activity.created`           | Activity timeline entry created.                                               |
| `transaction.created`        | Transaction created and initially evaluated.                                   |
| `transaction.status.updated` | Transaction status changed.                                                    |

Use the [create destination guide](/management-api/webhook/create-destination) for detailed event descriptions and common subscription sets.


## OpenAPI

````yaml PATCH /v3/webhook/destinations/{destination_uuid}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/webhook/destinations/{destination_uuid}/:
    patch:
      tags:
        - Webhook
      summary: Update webhook destination
      description: >-
        Update a webhook destination. **`subscribed_events` is REPLACED
        wholesale, not merged** — fetch first, append, resend. Secret is not
        rotated.
      operationId: update_webhook_destination
      parameters:
        - name: destination_uuid
          in: path
          required: true
          description: UUID of the destination to update.
          schema:
            type: string
            format: uuid
          example: 11111111-2222-3333-4444-555555555555
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: New human-readable name.
                url:
                  type: string
                  format: uri
                  description: New target URL. Must be unique within the application.
                enabled:
                  type: boolean
                  description: >-
                    Set to `false` to pause deliveries to this destination
                    without deleting it.
                webhook_version:
                  type: string
                  enum:
                    - v1
                    - v2
                    - v3
                  description: New payload schema version for future deliveries.
                subscribed_events:
                  $ref: '#/components/schemas/WebhookSubscribedEvents'
            examples:
              Pause destination:
                value:
                  enabled: false
              Add transaction events:
                value:
                  subscribed_events:
                    - status.updated
                    - data.updated
                    - transaction.created
                    - transaction.status.updated
              Move target URL:
                value:
                  label: Production session webhooks v2
                  url: https://api.yourapp.com/webhooks/didit/v2
      responses:
        '200':
          description: >-
            Updated webhook destination. Body has the same shape as `GET
            /v3/webhook/destinations/{destination_uuid}/`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    format: uuid
                  label:
                    type: string
                  url:
                    type: string
                    format: uri
                  enabled:
                    type: boolean
                  webhook_version:
                    type: string
                    enum:
                      - v1
                      - v2
                      - v3
                  secret_shared_key:
                    type: string
                  subscribed_events:
                    $ref: '#/components/schemas/WebhookSubscribedEvents'
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
                  summary:
                    type: object
                    properties:
                      total_deliveries:
                        type: integer
                      failed_deliveries:
                        type: integer
                      error_rate_percentage:
                        type: integer
                      min_response_time_ms:
                        type: integer
                        nullable: true
                      avg_response_time_ms:
                        type: integer
                        nullable: true
                      max_response_time_ms:
                        type: integer
                        nullable: true
                      last_delivery_at:
                        type: string
                        format: date-time
                        nullable: true
              examples:
                Paused:
                  value:
                    uuid: 11111111-2222-3333-4444-555555555555
                    label: Production session webhooks
                    url: https://yourapp.com/webhooks/didit
                    enabled: false
                    webhook_version: v3
                    secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ
                    subscribed_events:
                      - status.updated
                      - data.updated
                    created_at: '2026-01-04T08:00:00Z'
                    updated_at: '2026-05-17T11:02:55Z'
                    summary:
                      total_deliveries: 12453
                      failed_deliveries: 14
                      error_rate_percentage: 0
                      min_response_time_ms: 41
                      avg_response_time_ms: 187
                      max_response_time_ms: 2103
                      last_delivery_at: '2026-05-17T09:21:18Z'
        '400':
          description: >-
            Validation failed (duplicate URL, empty/unknown events list,
            malformed body).
          content:
            application/json:
              examples:
                Duplicate URL:
                  value:
                    url:
                      - >-
                        This webhook destination already exists for the
                        application.
                Empty events:
                  value:
                    subscribed_events:
                      - At least one subscribed event is required.
        '403':
          description: >-
            API key missing, malformed, expired, or scoped to a different
            application. Didit returns 403 (never 401) for all authentication
            failures on this endpoint.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '404':
          description: >-
            Destination with this UUID does not exist (or is deleted, or belongs
            to another application).
          content:
            application/json:
              examples:
                Not found:
                  value:
                    detail: Webhook destination not found.
        '429':
          description: Rate limit exceeded; back off and retry.
          content:
            application/json:
              examples:
                Throttled:
                  value:
                    detail: Request was throttled. Expected available in 30 seconds.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X PATCH
            'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/'
            \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "subscribed_events": [
                  "status.updated",
                  "data.updated",
                  "transaction.created"
                ]
              }'
        - lang: python
          label: Python
          source: |-
            import os

            import requests

            uuid = '11111111-2222-3333-4444-555555555555'
            resp = requests.patch(
                f'https://verification.didit.me/v3/webhook/destinations/{uuid}/',
                headers={
                    'x-api-key': os.environ['DIDIT_API_KEY'],
                    'Content-Type': 'application/json',
                },
                json={'enabled': False},
                timeout=10,
            )
            resp.raise_for_status()
            print('Paused destination:', resp.json()['label'])
        - lang: javascript
          label: JavaScript
          source: >-
            const uuid = '11111111-2222-3333-4444-555555555555';

            const resp = await
            fetch(`https://verification.didit.me/v3/webhook/destinations/${uuid}/`,
            {
              method: 'PATCH',
              headers: {
                'x-api-key': process.env.DIDIT_API_KEY,
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({ enabled: false }),
            });

            if (!resp.ok) throw new Error(await resp.text());

            console.log(await resp.json());
components:
  schemas:
    WebhookSubscribedEvents:
      type: array
      description: >-
        Event filter for this webhook destination. Didit delivers only webhooks
        whose event type exactly matches one of these values — there is no
        wildcard subscription. When sent, the list must contain at least one
        valid event (an explicit `[]` is rejected with 400); a destination whose
        list is empty (field omitted at create) receives nothing. On update the
        list is replaced wholesale, never merged.
      minItems: 1
      uniqueItems: true
      items:
        $ref: '#/components/schemas/WebhookEvent'
      example:
        - status.updated
        - data.updated
    WebhookEvent:
      type: string
      description: >-
        Supported webhook event name. Use these exact strings in
        `subscribed_events`; unsupported values are rejected.
      enum:
        - status.updated
        - data.updated
        - user.status.updated
        - user.data.updated
        - business.status.updated
        - business.data.updated
        - activity.created
        - transaction.created
        - transaction.status.updated
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````