자격 부여
자격 부여가 생성, 전달, 실패 또는 취소될 때 웹훅 엔드포인트로 전송되는 페이로드입니다.
자격 부여 웹훅 이벤트
고객의 자격 부여가 상태를 변경할 때마다 예를 들어 라이선스 키가 생성되거나, Discord 역할이 할당되거나, 다운로드 링크가 제공되거나, 액세스가 취소될 때 트리거됩니다. 이러한 이벤트에 구독하여 각 고객이 액세스할 수 있는 내용을 지속적으로 동기화하세요.EntitlementGrantResponse 페이로드를 공유합니다.
이벤트 트리거
entitlement_grant.created
방금 부여 행이 삽입되었습니다. 이 시점부터 부여는 안정적인id를 항상 가지고 있으며, 상태가 변경되더라도 마찬가지입니다. 이 이벤트를 사용하여 이행이 진행 중임을 기록하세요.
auto-fulfilled license keys의 경우 행이 status: "Delivered" 및 delivered_at가 채워진 상태로 직접 삽입되므로, 단일 created 이벤트 후에는 grant가 나중에 revoke되지 않는 한 추가 상태 변경이 발생하지 않습니다.
manually-fulfilled license keys(fulfillment_mode: manual가 있는 entitlement)의 경우 행이 status: "Pending" 상태로 도착하고 license_key 객체는 없습니다. 아직 key가 발급되지 않은 것입니다. 이 이벤트는 key가 fulfillment를 기다리고 있다는 신호입니다. POST /grants/{grant_id}/license-key를 통해 key를 제공하면 entitlement_grant.delivered가 발생합니다. Manual Fulfillment를 참조하세요.
그 외 모든 integration의 경우 행이 status: "Pending" 상태로 도착합니다. delivery가 완료되면 delivered 또는 failed 이벤트가 이어집니다:
- OAuth-based integrations(Discord, GitHub, Notion)에는 customer가 방문하여 동의를 완료해야 하는
oauth_url가 포함됩니다. customer가 authorize할 때까지 grant는Pending상태로 유지됩니다. - Platform-direct integrations(Telegram, Framer, Digital Files)은 platform call이 실행되는 동안에만 잠시
Pending상태에 머문 후Delivered로 전환됩니다.
pending에서 delivered로 전환되었습니다. 이제 고객은 자격 부여된 액세스를 받았습니다. 이 이벤트를 사용하여 작업 공간을 제공하거나, 맞춤 환영 이메일을 보내거나, “이행 완료” 플래그를 표시하는 등의 종속 기능을 잠금 해제하세요.
grant가 Pending에서 Delivered로 전환되었습니다. 이제 customer가 entitlement에 설명된 액세스 권한을 보유합니다. 이 이벤트를 사용하여 자체 시스템에서 종속 기능을 활성화하세요. 예를 들어 workspace를 provision하거나, 맞춤형 welcome email을 보내거나, “fulfilled” flag를 표시할 수 있습니다.
payload의 delivered_at field에는 delivery가 완료된 시점이 기록됩니다. 생성 시 Delivered 상태였던 grant의 경우 created 및 delivered 이벤트를 연속으로 수신합니다.
전달이 시도되었으나 다시 시도할 수 없는 오류로 실패했습니다. error_code와 error_message 필드는 실패 원인을 설명합니다. 일반적인 원인으로는 철회된 OAuth 토큰, 허가된 플랫폼 권한 거부 또는 삭제된 Discord 길드와 같은 대상 누락이 포함됩니다.
entitlement_grant.revoked
플랫폼 수준에서 액세스가 철회되었습니다: Discord 역할 제거, GitHub 협력자 제거, 라이선스 키 비활성화, 파일 다운로드 URL 더 이상 발행되지 않음.revocation_reason 필드는 트리거를 기록합니다.
페이로드 변형
data 필드는 항상 EntitlementGrantResponse 객체입니다. 두 가지 통합 유형은 추가 중첩 객체를 첨부합니다:
data field는 항상 EntitlementGrantResponse object입니다. payload에는 integration_type field가 포함되어 있어(예: license_key, digital_files, discord) grant type을 직접 식별할 수 있습니다. 세 가지 integration type에는 추가 중첩 object도 포함됩니다:
- **
license_key**는integration_type가license_key이고 key가 발급된 경우 포함됩니다. 생성된 key, 만료일 및 activation usage가 들어 있습니다. 아직Pending상태인 manually-fulfilled grant의 경우 grant를 fulfill할 때까지 이 object는null입니다. - **
digital_product_delivery**는integration_type가digital_files인 경우 포함됩니다. presigned download URL, 선택적instructions및 선택적external_url가 들어 있습니다. - **
feature**는integration_type가feature_flag인 경우 포함됩니다. grant가 부여하는 capability의feature_type및feature_id가 들어 있습니다.
null입니다. 관련 configuration은 grant가 아니라 entitlement 자체에 기록됩니다.
샘플 페이로드
라이선스 키 전송 완료 (entitlement_grant.delivered)
fulfillment_mode: manual를 사용하는 License Key entitlement가 포함된 product를 구매할 때 발생합니다. grant는 아직 license_key object가 없는 Pending 상태이며, merchant가 key를 제공해야 합니다.
구독 취소 시 부여 철회됨 (entitlement_grant.revoked)
전달 실패 (entitlement_grant.failed)
- 종속 기능 잠금 해제를 위해
entitlement_grant.delivered를 기다리세요.payment.succeeded이벤트는 금액이 정산되었다는 것을 알려줄 뿐이며, 고객이 GitHub 리포지토리나 Discord 역할을 가졌다는 것을 알려주지 않습니다.delivered이벤트가 이행을 위한 신뢰할 수 있는 출처입니다. revocation_reason를 유지 흐름에 매핑하세요.subscription_on_hold철회는 일반적으로 고객의 카드가 실패했고, 다음 갱신이 액세스를 재부여할 것이라는 것을 의미합니다.manual또는subscription_cancelled철회는 의도적입니다. 고객 메시지에서 이들을 다르게 처리하십시오.- 그랜트
id를 불변성 키로 사용하십시오. 단일 그랜트는 최대 하나의created이벤트와 최대 하나의 터미널 이벤트 (delivered또는failed), 최대 하나의revoked이벤트를 발생시킵니다. 웹훅 시스템의 재전달은 이벤트를 반복할 수 있습니다. 그랜트id플러스type에서 중복을 제거하십시오. - 통합 유형을 인식하기 위해
license_key와digital_product_delivery를 검사하세요. 그랜트 페이로드 자체에는 통합 유형이 포함되어 있지 않지만, 라이선스 키 및 디지털 파일 자격에서는 이 중 하나의 중첩 객체가 정확히 채워집니다. - OAuth 기반 부여의 경우
oauth_url를 고객에게 노출하세요. Discord, GitHub, Notion 가입자 흐름에 대한entitlement_grant.created이벤트에는oauth_url및oauth_expires_at가 포함됩니다. 이메일로 보내거나 앱에 표시하여 전달을 차단 해제하세요.
통합 팁
- 종속 기능을 활성화하기 전에
entitlement_grant.delivered를 기다리세요.payment.succeeded이벤트는 결제가 완료되었음을 의미할 뿐, customer가 아직 GitHub repo 또는 Discord role을 보유하고 있다는 뜻은 아닙니다. fulfillment의 source of truth는delivered이벤트입니다. revocation_reason를 retention flow에 매핑하세요.subscription_on_holdrevoke는 일반적으로 customer의 card 결제가 실패했으며 다음 renewal 시 액세스가 다시 부여된다는 의미입니다.manual또는subscription_cancelledrevoke는 의도적인 취소입니다. customer messaging에서 두 경우를 다르게 처리하세요.- grant의
id를 idempotency key로 사용하세요. 하나의 grant는 최대 하나의created이벤트와 최대 하나의 terminal event(delivered또는failed), 그리고 최대 하나의revoked이벤트를 발생시킵니다. webhook system의 재전달로 이벤트가 반복될 수 있으므로, grant의id와type를 기준으로 중복 제거하세요. integration_type를 읽어 grant type을 식별하세요. payload에는integration_type가 직접 포함됩니다(예:license_key,digital_files,discord).license_key및digital_product_delivery중첩 object는 해당 grant가 delivered되면 채워집니다. manually-fulfilled license-key grant는 fulfill할 때까지integration_type: "license_key"및null인license_key와 함께Pending상태로 유지됩니다.- OAuth-based grant의 경우
oauth_url를 customer에게 표시하세요. Discord, GitHub 또는 Notion subscriber flow의entitlement_grant.created이벤트에는oauth_url및oauth_expires_at가 포함됩니다. 이를 customer에게 email로 보내거나 app에 표시하여 delivery를 진행할 수 있도록 하세요.
Detailed view of a single entitlement grant: who it's for, its lifecycle state, and any integration-specific delivery payload.
Brand id this grant belongs to.
Identifier of the business that owns the grant.
Timestamp when the grant was created.
Identifier of the customer the grant was issued to.
Identifier of the entitlement this grant was issued from.
Unique identifier of the grant.
The integration type of the grant's entitlement (e.g. license_key).
discord, telegram, github, figma, framer, notion, digital_files, license_key, feature_flag Arbitrary key-value metadata recorded on the grant.
Lifecycle status of the grant.
Pending, Delivered, Failed, Revoked Timestamp when the grant was last modified.
Timestamp when the grant transitioned to delivered, when applicable.
Digital-product-delivery payload, present when the entitlement
integration is digital_files.
Machine-readable code reported when delivery failed, when applicable.
Human-readable message reported when delivery failed, when applicable.
Typed feature payload, present only when the entitlement integration is
feature_flag; null for every other integration type.
License-key delivery payload, present when the entitlement integration
is license_key.
Timestamp when oauth_url stops being valid, when applicable.
Customer-facing OAuth URL for OAuth-style integrations. Populated
during the customer-portal accept flow; null until the customer
completes that step, and on grants for non-OAuth integrations.
Identifier of the payment that triggered this grant, when applicable.
Reason recorded when the grant was revoked, when applicable.
Timestamp when the grant transitioned to revoked, when applicable.
Identifier of the subscription that triggered this grant, when applicable.