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

# Webhooks: Real-Time Event Notifications

> Receive real-time verification and fraud events. Set up webhooks in minutes and keep your system in sync with Dojah.

Webhooks allow your application to receive real-time updates from Dojah. For example, when a verification is completed, an address check fails, or a document analysis is flagged, a notification is received. This ensures your systems can react instantly to user events.

## How Webhooks Work

Once you subscribe to a service, Dojah will send an HTTP (usually a POST or a GET) request to your webhook URL whenever the relevant event occurs. Dojah’s request will include details of the event such as the service type and webhook URL.

Dojah’s Webhook services allow you to subscribe for webhooks, fetch all subscriptions, and also delete a webhook service.

<Accordion title="Subscribe to a Webhook">
  To start receiving webhooks, make a POST request with the service you want to monitor and the URL where Dojah should send updates. There is also the option of subscribing via the dashboard.

  <Tabs>
    <Tab title="From the Dashboard (No Code)">
      * Go to Developers > Webhooks
      * Click “Subscribe”
      * Fill in the form:
        * App Name – Select the app you want the webhook tied to
        * Webhook URL – Enter the endpoint where Dojah will send events
        * Service Name – Choose the service (e.g., KYC Widget, NGN Wallet)
    </Tab>

    <Tab title="Via the API">
      Send a `POST` request to the url below:

      ```json theme={null}
      	{{baseUrl}}api/v1/webhook/subscribe
      ```

      Pass the body parameters below:

      | Parameter | Type     | Description                                                                                                                                                                                                                                                                                      | Required |
      | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
      | `webhook` | `string` | webhook is the webhook url that allows Dojah to send (i.e “push”) data to your application as soon as an event occurs, Create a Test webhook url on webhook.site. Example [https://webhook.site/db8ad2b6-91b6-485b-9761-e546b540ccf6](https://webhook.site/db8ad2b6-91b6-485b-9761-e546b540ccf6) | required |
      | `service` | `string` | Type of services \[ sms, ngn\_wallet, kyc\_widget, address, AML Monitoring].                                                                                                                                                                                                                     | required |

      Response:

      ```json theme={null}
      	{
      	 "entity": "Webhook added successfully"
      	}

      ```

      An active webhook allows Dojah to send (i.e “push”) data to your application as soon as an event occurs.
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Fetch all Webhooks">
  To retrieve a list of all active webhook subscriptions:

  Request Url

  ```json theme={null}
    {{baseUrl}}api/v1/webhook/fetch
  ```

  Authorization

  | Header          | Type     | Description                                        |
  | --------------- | -------- | -------------------------------------------------- |
  | `AppId`         | `string` | Create an app to get your app ID on dashboard here |
  | `Authorization` | `string` | Private/secret key                                 |

  Response

  ```json theme={null}
  	{
      "entity": [
        {
          "app_id": "61e6bef823664a003647505f",
          "endpoint": "https://webhook.site/ec43b51e-eca7-42f0-b794-fb4f7b8c89d0",
          "environment": "live",
          "service": "sms",
          "confirmation_status": "DELIVERED",
          "date_created": "2022-01-18T14:31:36.810231+01:00",
          "date_updated": "2022-01-18T14:31:36.810319+01:00"
        },
        {
          "app_id": "61e6bef823664a003647505f",
          "endpoint": "https://webhook.site/ec43b51e-eca7-42f0-b794-fb4f7b8c89d0",
          "environment": "sandbox",
          "service": "sms",
          "confirmation_status": "DELIVERED",
          "date_created": "2022-01-18T14:22:22.398813+01:00",
          "date_updated": "2022-01-18T14:22:22.398857+01:00"
        }
      ]
    }

  ```
</Accordion>

<Accordion title="Delete Webhooks">
  This endpoint allows you to delete webhooks that no longer serve you. You can either delete via API or easily delete via the dashboard.

  Request URL

  ```json theme={null}
  	{{baseUrl}}api/v1/webhook/delete
  ```

  Authorization

  | Header          | Type     | Description                                        |
  | --------------- | -------- | -------------------------------------------------- |
  | `AppId`         | `string` | Create an app to get your app ID on dashboard here |
  | `Authorization` | `string` | Private/secret key                                 |

  Body Parameter

  | Parameter | Type     | Description                           | Required |
  | --------- | -------- | ------------------------------------- | -------- |
  | `service` | `string` | Type of services \[ sms, ngn\_wallet] | yes      |

  Response

  ```json theme={null}
  {
    "entity": "webhook deleted successfully"
  }
  ```
</Accordion>