africacompliancedata-com Webhooks API

openapi: 3.2.0
info:
  title: Africacompliancedata Com Webhooks API
  version: 1.0.0
  contact:
    name: Africa Compliance Data
    email: support@africacompliancedata.com
    url: https://africacompliancedata.com
  license:
    name: 'Proprietary: use under the Terms of Service'
    url: https://africacompliancedata.com/terms
  termsOfService: https://africacompliancedata.com/terms
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: africacompliancedata-com-openapi.json, africacompliancedata-com.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.africacompliancedata.com
security:
- ApiKey: []
- Bearer: []
tags:
- name: Webhooks
  description: 'Signed notifications when a country''s data changes, and the change log (every changed value with its reason): Developer and Pro for holiday changes, Compliance for every change.'
paths:
  /v1/webhooks:
    get:
      tags:
      - Webhooks
      operationId: listWebhooks
      summary: List your webhooks (with the last delivery result).
      description: 'Events go to keys on a plan with webhooks: each use of the key confirms its plan. Developer and Pro (and the grandfathered Starter and Pro) receive holiday changes only. A key not used for 14 days (13 at the earliest), moved to a plan without webhooks, cancelled or paused receives no events until it is used again on such a plan. Managing webhooks is not counted against the monthly quota.'
      responses:
        '200':
          description: Webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                  max:
                    type: integer
                    const: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/CompliancePlanRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Webhooks
      operationId: createWebhook
      summary: Create a webhook (returns its secret once).
      description: At most 3 webhooks per key (409 beyond). The body must be at most 4,000 bytes (413 beyond). The URL must be a public https address on the standard port, without credentials. On Developer and Pro, features is set to ['holidays'] (asking for another feature returns 403).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
                  maxLength: 500
                  description: Public https URL
                countries:
                  type: array
                  maxItems: 54
                  items:
                    type: string
                  description: ISO codes; empty or omitted = all
                features:
                  type: array
                  items:
                    type: string
                    enum:
                    - holidays
                    - vat
                    - wht
                    - tin_format
                    - filing_deadlines
                    - payroll
                  description: Empty or omitted = all. 'vat' includes the VAT rate history, 'wht' the tax treaties.
            example:
              url: https://example.com/acd
              countries:
              - KE
              - NG
              features:
              - vat
              - holidays
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    secret:
                      type: string
                      description: Signing secret (whsec_...), shown only once
                    note:
                      type: string
                      description: Reminder to store the secret now
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/CompliancePlanRequired'
        '409':
          description: 3 webhooks already exist for this key; delete one first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request body over 4,000 bytes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.africacompliancedata.com
  /v1/webhooks/{id}:
    delete:
      tags:
      - Webhooks
      operationId: deleteWebhook
      summary: Delete a webhook (and its queued events). Developer, Pro and Compliance
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: wh_3f9c0a1b2c3d4e5f
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: string
                    description: The deleted webhook id
                required:
                - deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/CompliancePlanRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.africacompliancedata.com
  /v1/webhooks/{id}/test:
    post:
      tags:
      - Webhooks
      operationId: testWebhook
      summary: Send a test event now. Developer, Pro and Compliance
      description: Delivers a 'test' event immediately (one attempt; at most 5 tests per minute per key, then 429) and returns the HTTP status your URL answered, or the network error.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivery result
          content:
            application/json:
              schema:
                type: object
                properties:
                  sent:
                    type: string
                    description: Event id (evt_test_...)
                  status:
                    type:
                    - integer
                    - string
                    description: 'HTTP status of your endpoint, or ''error: ...'''
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/CompliancePlanRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TestLimited'
    servers:
    - url: https://api.africacompliancedata.com
  /v1/changes:
    get:
      tags:
      - Webhooks
      operationId: getChanges
      summary: 'Change log: every changed value with its old and new value and the reason.'
      description: 'One entry per changed value, oldest first: old and new value, kind (law_change, correction, new_source, coverage), the date a law change applies from, the source and the data revision that made it. The same changes arrive in webhook events (''values''). The log starts on 2026-10-24; earlier changes are not listed. One request against the monthly quota.'
      parameters:
      - name: since
        in: query
        schema:
          type: string
          format: date
        description: Only entries logged on or after this date (YYYY-MM-DD)
        example: '2026-10-01'
      - name: country
        in: query
        schema:
          type: string
        description: Only this country (ISO 3166-1 alpha-2)
        example: SL
      responses:
        '200':
          description: Change log
          content:
            application/json:
              schema:
                type: object
                properties:
                  since:
                    type:
                    - string
                    - 'null'
                    format: date
                  country:
                    type:
                    - string
                    - 'null'
                  scope:
                    type: string
                    enum:
                    - all
                    - holidays
                    description: 'holidays: your plan''s log lists holiday changes only'
                  count:
                    type: integer
                  changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Change'
                  notes:
                    type: array
                    items:
                      type: string
                  dataset_version:
                    type: string
                  data_revision:
                    $ref: '#/components/schemas/DataRevision'
                  disclaimer:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          description: Free plan (the change log is in Developer, Pro and Compliance), or the key is paused for review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.africacompliancedata.com
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    DataRevision:
      type: string
      description: 'Short commit id of the data the answer was built from (e.g. 928cb72b). dataset_version is the build date: the daily rebuild changes it with no data change, while data_revision changes only when the data does. Keep it with saved results to know exactly which data you used.'
      example: 928cb72b
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        countries:
          type: array
          items:
            type: string
        features:
          type: array
          items:
            type: string
        created:
          type: string
          format: date-time
        last_delivery:
          type:
          - object
          - 'null'
          properties:
            at:
              type: string
              format: date-time
            status:
              type:
              - integer
              - string
            event:
              type: string
    Change:
      type: object
      description: One changed value
      properties:
        date:
          type: string
          format: date
          description: Day the change was logged
        country:
          type: string
        feature:
          type: string
          enum:
          - holidays
          - vat
          - wht
          - tin_format
          - filing_deadlines
          - treaties
          - finance_law
          - history
          - payroll
          - other
        path:
          type: string
          description: The value inside the country's data, e.g. wht/items[payment_type=royalties]/non_resident_rate
        old:
          description: 'Value before (null: not given before)'
        new:
          description: 'Value after (null: no longer given)'
        kind:
          type: string
          enum:
          - law_change
          - correction
          - new_source
          - coverage
          description: 'law_change: the law changed; correction: our record was wrong (the law did not change); new_source: same value, better source; coverage: a value not given before'
        effective_from:
          type:
          - string
          - 'null'
          format: date
          description: 'law_change: the day the new value applies (null if not known)'
        source:
          type: string
          description: The law or text the new value comes from
        source_url:
          type:
          - string
          - 'null'
        source_note:
          type: string
          description: Why there is no link
        commit:
          type:
          - string
          - 'null'
          description: Data revision that made the change
  responses:
    TestLimited:
      description: At most 5 test deliveries per minute per key, or the plan rate limit, or key checks busy (many new keys from your network); see Retry-After
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Missing or invalid parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: Key check temporarily unavailable, or webhook storage unavailable (webhook endpoints); retry after Retry-After seconds
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Unknown country, path or webhook id
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'Monthly quota reached (until 00:00 UTC on the 1st; X-Quota-Limit and X-Quota-Remaining: 0), rate limit for the plan exceeded, or key checks busy (many new keys from your network); see Retry-After'
      headers:
        Retry-After:
          schema:
            type: integer
        X-Quota-Limit:
          schema:
            type: integer
        X-Quota-Remaining:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CompliancePlanRequired:
      description: 'Webhooks: not on Free, and holiday changes only on Developer and Pro; finance-law digests: Compliance only (or the key is paused for review)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
    Bearer:
      type: http
      scheme: bearer
      description: The same API key as a bearer token.
x-refined-from:
- africacompliancedata-com-openapi.json
- africacompliancedata-com.json